`DESIGN-generator-real-code.md`

120 lines
# TK-10634 #2 — DESIGN: DWHD→real-code generator redesign (Cycle 3 draft)

## Problem
`hollywood-import/{assign-sku,hollywood-create,hollywood-add-yard}.mjs` mint a sequential
`DWHD-<n>` (base 500000) for each Momentum colorway and stamp `pl_brand='Hollywood
Wallcoverings'`. Because Hollywood is a DW **brand**, not an external vendor, this DW-vendor
SKU is fabricated — it buries the product's real Momentum identity (the exact bug TK-10630
cleaned up across ~7k live products). The kill-switch (`~/.dw-fixer-stop`) + the assign-sku
`--commit` guard currently FREEZE this path; this doc is the redesign that lets it un-freeze.

## Current flow (frozen)
1. `assign-sku.mjs` — `UPDATE momentum_colorways SET dw_sku='DWHD-'||nextval, pl_brand=... WHERE dw_sku IS NULL`.
2. `hollywood-create.mjs` — creates the Shopify product + `${dw}-Sample` variant ($4.25).
3. `hollywood-add-yard.mjs` — adds the "Sold Per Yard" variant `sku: dw+'-Yard'`.
Result: `DWHD-508xxx-Sample` / `DWHD-508xxx-Yard` + `DWHW2`-style dw_sku metafields.

## Key finding (why this isn't a trivial swap)
There are TWO code eras:
- **Legacy real codes** (`HWC-`, `XWH-`, `NOC-`, `FLS-`, `HLW-`, `XJP-`, `XJB-`…) = Momentum's
  historical BOOK/line codes. `HWC-61244` carries `manufacturer_sku=61244` but does NOT
  resolve to any record in today's live Momentum Meilisearch feed (discontinued/renamed).
  These are the real mfr numbers and MUST be PRESERVED, never re-minted.
- **New colorways from the live feed** = the only place the generator runs. The feed record
  carries the authoritative identity: `number` (mfr SKU, 8-digit e.g. 09221958),
  `pattern_name`, `preferred_color_name`, `preferred_color_number`, `product_line.code`,
  `series`, `collections`, `category_name`.

## Design principle
A Momentum→Hollywood product's identity must derive from its **real Momentum `number`**,
never a sequential DW-vendor mint. Correlation, not fabrication.

## Proposed scheme (for Steve's decision)
- `manufacturer_sku` metafield = the feed **`number`** (authoritative, always).
- `dw_sku` / variant base = a NON-fabricated code. Options (DECISION NEEDED):
  - **Option A (recommended):** `HW-<number>` (brand-agnostic-safe prefix `HW` + the real
    Momentum number). Deterministic, collision-free (number is unique), traceable, never a
    fake sequential. Variants `HW-<number>-sample` / `-yard`.
  - **Option B:** reuse the Momentum `product_line.code`/`series` as the prefix if it maps to
    the legacy book prefixes (HWC/XWH/…). Needs a verified line-code→prefix table first
    (the feed `product_line.code` seen so far = `mtw`, which does NOT match the legacy
    prefixes — so this option is blocked until that mapping is confirmed to exist).
  - **Option C:** bare `number` as the SKU (simplest, but loses the human-readable brand cue).
- Suffix scheme stays `-sample` / `-yard` (already the standard; TK-10630 normalized it).

## Migration / backfill (existing ~2,538 DWHD-coded products)
- **2,156 already have a real `manufacturer_sku`** → backfill dw_sku from it (Option A: `HW-<mfr>`).
- **784 matched the live feed by `number`** (deep-recovered.json) → set from the feed record.
- **~382 truly orphaned** (no mfr, discontinued) → leave archived / manual (2 active already archived).
- All backfills are metafield/variant writes = GATED (draft to pending-approval, dry-run first).

## Rollout
1. Steve picks A/B/C.
2. Rewrite the 3 scripts to compute the code from `number` (remove the `nextval` mint).
3. Dry-run on a handful of new colorways; verify against the canary (`dw-hollywood-sku-canary`
   must stay PASS — the FABRICATED regex already catches any `DW`-prefixed regression).
4. Backfill existing DWHD products (gated batch, like the TK-10630 passes).
5. Remove `~/.dw-fixer-stop` only after 3+4 verify clean.

## Open questions for Steve
- Prefix choice (A `HW-<number>` vs C bare number)?
- Do legacy `HWC/XWH/NOC` products keep their codes as-is (recommended yes) or get renamed to
  the new scheme (NOT recommended — churn + redirect cost, and they're already real)?
- Is `manufacturer_sku` = feed `number` (8-digit) or the legacy 6-digit pattern number when both exist?

---
## Cody-gate revisions (Cycle 3) — resolve BEFORE any code
1. **CANARY GAP (blocker):** the guard `FABRICATED=/^DW[A-Z]{1,4}\d?-\d/i` only catches `DW*`
   codes. A new `HW-`/bare-number scheme would pass clean → the canary goes blind to a future
   re-mint in the new space. The redesign MUST ship an updated guard: for Option A, add the
   new prefix to a "sequential-mint" detector (flag `HW-` codes NOT backed by a real feed
   `number`); for Option C, assert the SKU IS a known Momentum `number`. No code until the
   canary evolves with it.
2. **Metafield vs variant (correction to Cody):** `dw_sku` DOES drive the variant SKU
   (`hollywood-create` sets `${dw}-Sample`). So the 642-active backfill IS a customer-facing
   variant-SKU change (order-history / PDP), BUT it does NOT create redirects — Shopify
   redirects fire on HANDLE changes only (TK-10630 changed thousands of variant SKUs with 0
   redirects). So the redirect cap (TK-10640) is NOT threatened by the backfill; handles are
   untouched. The doc must state this split explicitly: variant+metafield change, handle unchanged.
3. **Option C gets a fair hearing (Strategist/Designer):** `HW-` is still a BRAND-derived
   prefix (Hollywood) — the same brand-as-vendor sin in a thinner disguise, and it violates
   this doc's own principle ("derive from the real Momentum number, never a DW/brand mint").
   **Bare `number` (Option C) is the only principle-consistent choice** — the "human-readable
   brand cue" objection is a UX preference, not a design principle. RECOMMENDATION FLIPPED: C > A.
4. **Uniqueness is asserted, not proven:** "the `number` is unique" is inferred from a 20k feed
   snapshot, not Momentum's numbering spec. Before Option C, confirm `number` is globally unique
   across ALL Momentum lines (wallcovering + acoustic + textile), else `HW-<number>`/bare collides.

## Uniqueness — RESOLVED (2026-08-17)
Verified: 20,000 feed records → 20,000 distinct `number`s, **0 cross-category collisions**
(wallcovering + acoustic + textile share one non-overlapping number space). Option C (bare
`number` SKU) is collision-safe within the current catalog. Caveat: the feed API caps at 20k
records; if Momentum's true catalog exceeds 20k, re-verify before go-live. **RECOMMENDATION: Option C.**

## ⚠ CORRECTION (Steve: "always pl momentum", 2026-08-17) — Option C RETRACTED
The customer-facing SKU must ALWAYS carry a Hollywood PRIVATE-LABEL prefix; the raw Momentum
`number` must NOT be the visible SKU (it's a competitor-traceable supplier code).
- **Option C (bare number) is WRONG** — it exposes Momentum's own product number customer-facing.
  (Tested live on 782 → caught after 70 → all 70 REVERTED to DWHD, 0 errors, no harm.)
- **CORRECTED SCHEME = Option A:** customer-facing `dw_sku`/variant = a Hollywood private-label
  prefix + number (e.g. `HW-<number>` or the legacy per-collection prefix like `HWC-`), which
  is private-labeling — NOT the brand-as-vendor sin. The real Momentum `number` lives ONLY in
  the internal `manufacturer_sku` metafield (never customer-facing).
- Cody's "HW- is a brand prefix" objection is OVERRULED by this rule: the brand prefix is the
  REQUIRED private-label wrapper. The original sin was the *sequential DW-vendor mint* (DWHD)
  divorced from the real product — not the presence of a brand prefix.
- OPEN for Steve: prefix = single `HW-` for all, or preserve/derive the legacy per-collection
  prefixes (HWC/XWH/NOC…)? And is the numeric part the Momentum `number` or a DW-assigned one?

## DTD DECISION (2026-08-17, 5/5 unanimous B; Cody dissent A)
**B: Leave the existing ~2,538 as DWHD (opaque, non-leaking, real # in manufacturer_sku); fix the
GENERATOR so NEW products are born with the correct Hollywood private-label code.**
- Existing DWHD products stay — no churn on already-compliant live SKUs.
- The dw-hollywood-sku-canary stays at a truthful baseline-aware WARN for the known DWHD backlog
  (regression detection intact); it is NOT re-tuned to bless fabricated codes.
- Correction (Cody): 864 ACTIVE orphans (not 382) — they remain DWHD, non-leaking; no forced churn.
- NEXT (generator forward-fix, still Steve-gated build): rewrite assign-sku/hollywood-create/
  hollywood-add-yard to mint a Hollywood private-label code (NOT bare Momentum number, NOT sequential
  DW-vendor) + keep the real number in manufacturer_sku + add the canary's forward guard. Kill-switch
  stays on until that ships.