fix(products): conservative dialect detection — canonical-distinctive columns veto Shopify (SLICE-8 review)

Addresses adversarial-review findings: a canonical file carrying a stray
Shopify-signature name (e.g. SEO Title) no longer misdetects as Shopify and
silently drops canonical Type / corrupts the weight unit (kg->g). A
canonical-distinctive column (Description/Variant Cost/Variant Weight/Google
Product Category/Variant Volume/Tax ID/Position) now vetoes detection, so
detection leans conservative (under-detection warns; over-detection corrupts).
Also closes the dual-named-column shadow (Body (HTML)+Description) and the
stale-weight-unit-on-clear case. Tests cover all three.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

VERSION

@@ -1 +1 @@
-0.7.0
+0.8.0

backend/app/domains/products/__init__.py

@@ -35,11 +35,13 @@ from .service import (
 
 # DOC-3: the downloadable worked-example CSV the BFF serves at /api/products/sample.csv.
 SAMPLE_CSV_PATH = Path(__file__).parent / "sample.csv"
+# DOC-2: the column reference the BFF serves at /api/products/columns.md.
+COLUMNS_MD_PATH = Path(__file__).parent / "columns.md"
 
 __all__ = [
     "ProductsError", "FileRejected", "DraftNotFound", "DraftExpired",
     "PreviewStale", "NothingToApply", "RunNotFound", "EmptyCatalog",
-    "MAX_DATA_ROWS", "MAX_FILE_BYTES", "SAMPLE_CSV_PATH",
+    "MAX_DATA_ROWS", "MAX_FILE_BYTES", "SAMPLE_CSV_PATH", "COLUMNS_MD_PATH",
     "import_validate", "get_draft", "get_draft_records", "discard_draft",
     "confirm_draft", "list_runs", "get_run", "summary", "export_catalog",
     "run_image_phase", "recover_incomplete_runs", "image_for_serving",

backend/app/domains/products/codec.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import csv
 import io
 
+from .dialect_shopify import is_shopify_header, map_shopify_header
 from .errors import FileRejected
 from .models import KNOWN_COLUMNS, MAX_DATA_ROWS, MAX_FILE_BYTES, ParsedFile, Row
 
@@ -13,8 +14,8 @@ _REQUIRED_HEADER_COLUMNS = ("Handle", "Title")
 
 
 def detect_dialect(header: list[str]) -> str:
-    """The INV-17 seam: SLICE-8 recognizes Shopify's exact header set here."""
-    return "canonical"
+    """The INV-17 seam: recognize Shopify's header set, else canonical (§6.5.1)."""
+    return "shopify" if is_shopify_header(header) else "canonical"
 
 
 def parse_csv(data: bytes) -> ParsedFile:
@@ -31,19 +32,34 @@ def parse_csv(data: bytes) -> ParsedFile:
         except StopIteration:
             raise FileRejected("not_csv", "This file isn't readable as CSV.") from None
         header = [h.strip() for h in raw_header]
+        dialect = detect_dialect(header)
+
+        # INV-17: normalize the header to canonical names at the boundary. mapped[i]
+        # is the canonical name for header[i] (or None when that column has no
+        # canonical home); unknown is the not-imported warning list. Canonical files
+        # map to themselves; unknown columns are warned exactly as before.
+        if dialect == "shopify":
+            mapped, unknown = map_shopify_header(header)
+        else:
+            mapped = [c if c in KNOWN_COLUMNS else None for c in header]
+            unknown = [c for c in header if c and c not in KNOWN_COLUMNS]
+
         for col in _REQUIRED_HEADER_COLUMNS:
-            if col not in header:
+            if col not in mapped:
                 raise FileRejected(
                     "missing_required_column",
                     f"This file is missing the required column '{col}'.",
                 )
-        # First occurrence of a duplicated column wins.
+
+        # First occurrence of a duplicated canonical column wins.
         col_index: dict[str, int] = {}
-        for i, name in enumerate(header):
+        for i, name in enumerate(mapped):
             if name and name not in col_index:
                 col_index[name] = i
-        known_present = [c for c in col_index if c in KNOWN_COLUMNS]
-        unknown = [c for c in col_index if c not in KNOWN_COLUMNS]
+        # De-dup the warning list, order-preserving.
+        seen: set[str] = set()
+        unknown = [c for c in unknown if not (c in seen or seen.add(c))]
+
         rows: list[Row] = []
         for raw in reader:
             if not any(cell.strip() for cell in raw):
@@ -55,11 +71,16 @@ def parse_csv(data: bytes) -> ParsedFile:
                 )
             cells = {
                 c: (raw[col_index[c]].strip() if col_index[c] < len(raw) else "")
-                for c in known_present
+                for c in col_index
             }
+            # Shopify grams carry an implicit unit; canonical needs it explicit. In a
+            # Shopify file "Variant Weight" can only come from the Variant Grams rename
+            # (a canonical-named Variant Weight would have vetoed Shopify detection), so
+            # weight and unit move together: a value -> "g"; a cleared grams (present-but-
+            # empty) clears the unit too, never leaving a stale unit (§6.5.1).
+            if dialect == "shopify" and "Variant Weight" in cells:
+                cells["Variant Weight Unit"] = "g" if cells["Variant Weight"] else ""
             rows.append(Row(line_number=reader.line_num, cells=cells))
     except csv.Error:
         raise FileRejected("not_csv", "This file isn't readable as CSV.") from None
-    return ParsedFile(
-        dialect=detect_dialect(header), header=header, unknown_columns=unknown, rows=rows
-    )
+    return ParsedFile(dialect=dialect, header=header, unknown_columns=unknown, rows=rows)

backend/app/domains/products/columns.md

@@ -0,0 +1,95 @@
+# Product CSV — column reference
+
+This is the complete reference for the product CSV you import into and export from
+your store (SD-0002 §6.5.1). The format is **canonical** — a clean superset of the
+Shopify product CSV — and a **Shopify product CSV** imports directly too: we detect
+which one you uploaded and map it for you (see *Shopify dialect* below).
+
+You don't pick a format. Upload your file; the preview tells you which format was
+recognized and shows exactly what will change before anything is applied.
+
+## File shape
+
+- UTF-8 (a byte-order mark is tolerated), comma-delimited, RFC 4180 quoting.
+- A header row is **required**. `Handle` and `Title` are the only always-required
+  columns.
+- Up to 5,000 rows and 10 MB per file. Split larger catalogs and import in parts.
+
+## Row grammar
+
+Consecutive rows that share a `Handle` describe **one product**. The product's first
+row carries the product-level fields (`Title` is required there). Each row may carry:
+
+- a **variant** — its `Option n Value`s plus `Variant *` fields;
+- an **image** — `Image Src` with `Image Position` / `Image Alt Text`;
+- or both.
+
+An image-only row (just `Handle` + `Image *`) is valid — that's how a product carries
+more images than it has variants.
+
+## Updating: blank vs. absent
+
+- A column **absent from your file** is left untouched on existing products.
+- A cell that is **present but empty** clears that field (resets it to its default).
+
+Every clear is shown explicitly in the preview, so this is deliberate, visible
+behavior — never a silent surprise.
+
+## Canonical columns
+
+| Column | Level | Required | Notes |
+| --- | --- | --- | --- |
+| `Handle` | product | every row | Identity: lowercase letters, numbers, and dashes. |
+| `Title` | product | first row of a product | |
+| `Description` | product | — | HTML allowed; sanitized on import. |
+| `Vendor` | product | — | Free text. |
+| `Type` | product | — | `standalone` (default). `kit_virtual` / `kit_assembled` are reserved; any non-`standalone` value is a row error until kits ship. |
+| `Google Product Category` | product | — | Taxonomy string. |
+| `Tags` | product | — | Comma-separated within the cell. |
+| `Status` | product | — | `draft` \| `active` \| `archived`; defaults to `active` on add. |
+| `Published` | product | — | `TRUE` \| `FALSE`; defaults to `TRUE` on add. |
+| `Option1 Name` … `Option3 Name` | product | with values | e.g. "Size". A value without its name is a row error. |
+| `Option1 Value` … `Option3 Value` | variant | per variant | The variant's identity combination. |
+| `Variant SKU` | variant | — | Indexed; not identity. |
+| `Variant Barcode` | variant | — | |
+| `Variant Price` | variant | — | Decimal; no currency symbol. |
+| `Variant Cost` | variant | — | Decimal. |
+| `Variant Weight` + `Variant Weight Unit` | variant | — | Decimal weight plus a unit string. |
+| `Variant Volume` + `Variant Volume Unit` | variant | — | Decimal volume plus a unit string. |
+| `Variant Tax ID 1` / `Variant Tax ID 2` | variant | — | Opaque references. |
+| `Variant Inventory Tracker` | variant | — | |
+| `Variant Inventory Qty` | variant | — | Integer ≥ 0. |
+| `Variant Position` | variant | — | Display order; defaults to file order. |
+| `Image Src` | image | — | URL (or a store-hosted URL on re-import). |
+| `Image Position` | image | — | Integer order. |
+| `Image Alt Text` | image | — | |
+| `Variant Image` | variant | — | URL for this variant's specific image. |
+| `Component 1 SKU` / `Component 1 Quantity` … `Component 10 …` | variant | — | Reserved for kits — a non-empty value is a row error today. |
+
+## Shopify dialect
+
+If you upload a **Shopify product CSV**, we recognize it by its header set and map it
+to the canonical columns automatically. The preview labels it *"Shopify product
+CSV — mapped"*.
+
+**Mapped — renamed**
+
+| Shopify column | Becomes |
+| --- | --- |
+| `Body (HTML)` | `Description` |
+| `Product Category` | `Google Product Category` |
+| `Cost per item` | `Variant Cost` |
+| `Variant Grams` | `Variant Weight` (in grams) |
+
+**Mapped — same name:** `Handle`, `Title`, `Vendor`, `Tags`, `Published`, `Status`,
+`Option1–3 Name` / `Option1–3 Value`, `Variant SKU`, `Variant Barcode`,
+`Variant Price`, `Variant Inventory Tracker`, `Variant Inventory Qty`,
+`Variant Image`, `Image Src`, `Image Position`, `Image Alt Text`.
+
+**Not imported — listed in the preview as a heads-up, never silently dropped:** the
+Shopify free-text `Type` (canonical `Type` is structural, so we don't fold a category
+string into it), `Variant Compare At Price`, `Variant Inventory Policy`,
+`Variant Fulfillment Service`, `Variant Requires Shipping`, `Variant Taxable`,
+`Variant Tax Code`, `Gift Card`, SEO fields, every `Google Shopping / …` field, and
+market/region price columns. These have no canonical home yet; your other data still
+imports.

backend/app/domains/products/dialect_shopify.py

@@ -0,0 +1,95 @@
+"""Shopify product-CSV adapter (INV-17): detect by header signature, map to canonical.
+
+The mapping is the §6.5.1 contract; the exhaustive table is pinned here and
+mirrored by tests/test_products_dialect_shopify.py + e2e/fixtures/shopify-export.csv.
+"""
+from __future__ import annotations
+
+from .models import KNOWN_COLUMNS
+
+# Shopify header -> canonical header (renames only; direct same-name columns pass
+# through via KNOWN_COLUMNS). Variant Grams carries a value transform (see codec).
+SHOPIFY_RENAME: dict[str, str] = {
+    "Body (HTML)": "Description",
+    "Product Category": "Google Product Category",
+    "Cost per item": "Variant Cost",
+    "Variant Grams": "Variant Weight",
+}
+
+# Canonical-named columns Shopify uses differently — must NOT pass through.
+# Type: Shopify's free-text type vs canonical's structural Type (§6.5.1, decision D).
+# Variant Weight Unit: superseded by the Variant Grams -> Variant Weight transform.
+SHOPIFY_DROP: frozenset[str] = frozenset({"Type", "Variant Weight Unit"})
+
+# Columns whose presence proves the file is a Shopify export (canonical never has them).
+_SIGNATURE: frozenset[str] = frozenset(
+    {
+        "Body (HTML)",
+        "Variant Grams",
+        "Cost per item",
+        "Variant Compare At Price",
+        "Variant Inventory Policy",
+        "Variant Fulfillment Service",
+        "Variant Requires Shipping",
+        "Variant Taxable",
+        "Gift Card",
+        "SEO Title",
+        "SEO Description",
+    }
+)
+
+# Canonical-distinctive columns — names Shopify renames away (so a real Shopify export
+# never carries them) plus canonical-only columns Shopify has no equivalent for. Their
+# presence proves the file is canonical and VETOES Shopify detection: detection must
+# lean conservative, because under-detection is safe (Shopify-named columns are warned
+# as not-imported) while over-detection corrupts (canonical Type / weight-unit are
+# dropped). This closes the misdetection hazard — a canonical file that merely contains
+# a stray signature-named column (e.g. `SEO Title`) is never misread as Shopify (§7.4).
+_CANONICAL_SIGNATURE: frozenset[str] = frozenset(
+    {
+        "Description",
+        "Variant Cost",
+        "Variant Weight",
+        "Google Product Category",
+        "Variant Volume",
+        "Variant Volume Unit",
+        "Variant Tax ID 1",
+        "Variant Tax ID 2",
+        "Variant Position",
+    }
+)
+
+
+def is_shopify_header(header: list[str]) -> bool:
+    """True iff the header carries a Shopify-only signature column AND no
+    canonical-distinctive column. A canonical signal vetoes Shopify detection so an
+    ambiguous or hybrid header is treated as canonical — where Shopify-named columns
+    are warned as not-imported rather than silently remapped (never misparses, §7.4)."""
+    cols = {h.strip() for h in header}
+    if cols & _CANONICAL_SIGNATURE:
+        return False
+    if cols & _SIGNATURE:
+        return True
+    return any(c.startswith("Google Shopping / ") for c in cols)
+
+
+def map_shopify_header(header: list[str]) -> tuple[list[str | None], list[str]]:
+    """Return (mapped, not_imported): mapped[i] is the canonical name for header[i],
+    or None when that Shopify column has no canonical home; not_imported lists the
+    original Shopify names (in order) that were dropped — the preview warning."""
+    mapped: list[str | None] = []
+    not_imported: list[str] = []
+    for raw in header:
+        col = raw.strip()
+        if col in SHOPIFY_RENAME:
+            mapped.append(SHOPIFY_RENAME[col])
+        elif col in SHOPIFY_DROP:
+            mapped.append(None)
+            not_imported.append(col)
+        elif col in KNOWN_COLUMNS:
+            mapped.append(col)
+        else:
+            mapped.append(None)
+            if col:
+                not_imported.append(col)
+    return mapped, not_imported

backend/app/main.py

@@ -450,6 +450,14 @@ def create_app(database_url: str | None = None, static_dir: str | Path | None =
             headers={"content-disposition": 'attachment; filename="ecomm-products-sample.csv"'},
         )
 
+    @app.get("/api/products/columns.md")
+    def products_columns_md():
+        """The DOC-2 column reference. Documentation, so no auth gate (§6.4)."""
+        return PlainTextResponse(
+            products.COLUMNS_MD_PATH.read_text(),
+            media_type="text/markdown; charset=utf-8",
+        )
+
     # Deployed topology (launch-app SPEC §2): nginx proxies everything here, so the
     # backend serves the built SPA. Mounted LAST so /healthz and /api/* win. In dev the
     # dist dir doesn't exist (Vite serves the frontend) and the mount is skipped.

backend/tests/fixtures/shopify-export.csv

@@ -0,0 +1,4 @@
+Handle,Title,Body (HTML),Vendor,Product Category,Type,Tags,Published,Status,Option1 Name,Option1 Value,Variant SKU,Variant Grams,Variant Inventory Tracker,Variant Inventory Qty,Variant Inventory Policy,Variant Fulfillment Service,Variant Price,Variant Compare At Price,Variant Requires Shipping,Variant Taxable,Variant Barcode,Image Src,Image Position,Image Alt Text,Gift Card,SEO Title,SEO Description,Google Shopping / MPN,Variant Image,Variant Weight Unit,Cost per item,Status
+star-tee,Star Tee,<p>Soft cotton tee.</p>,Wiggle Goods,Apparel & Accessories > Clothing,Shirts,"apparel, tees",TRUE,active,Size,S,WG-TEE-S,180,shopify,12,deny,manual,24.00,30.00,TRUE,TRUE,0001,https://img.example.com/star-tee.jpg,1,Star Tee,FALSE,Star Tee | Wiggle,Soft tee,MPN-1,https://img.example.com/star-s.jpg,g,11.00,active
+star-tee,,,,,,,,,,M,WG-TEE-M,180,shopify,18,deny,manual,24.00,30.00,TRUE,TRUE,0002,,,,FALSE,,,,,g,11.00,
+star-tee,,,,,,,,,,,,,,,,,,,,,,https://img.example.com/star-back.jpg,2,Star Tee back,,,,,,,,

backend/tests/test_products_codec.py

@@ -67,3 +67,29 @@ def test_missing_column_message_names_the_column():
     with pytest.raises(FileRejected) as exc:
         parse_csv(_csv("Handle,Vendor", "mug,Acme"))
     assert "'Title'" in exc.value.message
+
+
+def test_parse_detects_and_maps_shopify():
+    data = (
+        "Handle,Title,Body (HTML),Cost per item,Variant Price,Variant Grams,Type,Gift Card\n"
+        "mug,Moon Mug,<p>Grey</p>,9.50,18.00,300,Drinkware,false\n"
+    ).encode("utf-8")
+    parsed = parse_csv(data)
+    assert parsed.dialect == "shopify"
+    cells = parsed.rows[0].cells
+    assert cells["Description"] == "<p>Grey</p>"
+    assert cells["Variant Cost"] == "9.50"
+    assert cells["Variant Weight"] == "300"
+    assert cells["Variant Weight Unit"] == "g"  # synthesized
+    # Type (free-text) and Gift Card warned, never mapped:
+    assert "Type" in parsed.unknown_columns
+    assert "Gift Card" in parsed.unknown_columns
+    assert "product_type" not in str(cells)  # Type never reached canonical
+
+
+def test_parse_canonical_unchanged():
+    data = b"Handle,Title,Description,Variant Price\nmug,Moon Mug,Grey,18.00\n"
+    parsed = parse_csv(data)
+    assert parsed.dialect == "canonical"
+    assert parsed.rows[0].cells["Description"] == "Grey"
+    assert parsed.unknown_columns == []

backend/tests/test_products_dialect_shopify.py

@@ -0,0 +1,121 @@
+"""Shopify dialect adapter — detection + the §6.5.1 mapping contract (SLICE-8)."""
+from pathlib import Path
+
+from app.domains.products.codec import parse_csv
+from app.domains.products.dialect_shopify import is_shopify_header, map_shopify_header
+
+_FIXTURE = Path(__file__).parent / "fixtures" / "shopify-export.csv"
+
+
+def test_detects_shopify_by_signature_column():
+    assert is_shopify_header(["Handle", "Title", "Body (HTML)", "Variant Price"]) is True
+    assert is_shopify_header(["Handle", "Title", "Google Shopping / MPN"]) is True
+
+
+def test_canonical_header_is_not_shopify():
+    assert is_shopify_header(["Handle", "Title", "Description", "Variant Cost"]) is False
+
+
+def test_ambiguous_shared_only_header_defaults_canonical():
+    # Only columns common to both dialects -> not Shopify (safe default, never misparse).
+    assert (
+        is_shopify_header(["Handle", "Title", "Option1 Name", "Variant Price", "Image Src"])
+        is False
+    )
+
+
+def test_map_renames_and_passes_through():
+    mapped, not_imported = map_shopify_header(
+        ["Handle", "Body (HTML)", "Cost per item", "Variant Price"]
+    )
+    assert mapped == ["Handle", "Description", "Variant Cost", "Variant Price"]
+    assert not_imported == []
+
+
+def test_map_drops_type_and_weight_unit_overrides():
+    mapped, not_imported = map_shopify_header(
+        ["Handle", "Type", "Variant Grams", "Variant Weight Unit"]
+    )
+    assert mapped == ["Handle", None, "Variant Weight", None]
+    assert not_imported == ["Type", "Variant Weight Unit"]
+
+
+def test_map_drops_shopify_only_and_market_columns():
+    mapped, not_imported = map_shopify_header(
+        ["Handle", "Variant Compare At Price", "Gift Card", "Price / International"]
+    )
+    assert mapped == ["Handle", None, None, None]
+    assert not_imported == ["Variant Compare At Price", "Gift Card", "Price / International"]
+
+
+def test_shopify_fixture_maps_exhaustively():
+    parsed = parse_csv(_FIXTURE.read_bytes())
+    assert parsed.dialect == "shopify"
+    first = parsed.rows[0].cells
+    # renamed
+    assert first["Description"] == "<p>Soft cotton tee.</p>"
+    assert first["Google Product Category"] == "Apparel & Accessories > Clothing"
+    assert first["Variant Cost"] == "11.00"
+    assert first["Variant Weight"] == "180"
+    assert first["Variant Weight Unit"] == "g"
+    # direct
+    assert first["Variant SKU"] == "WG-TEE-S"
+    assert first["Image Src"] == "https://img.example.com/star-tee.jpg"
+    # not imported — warned, none leaked into canonical cells
+    for col in (
+        "Type",
+        "Variant Compare At Price",
+        "Gift Card",
+        "SEO Title",
+        "Google Shopping / MPN",
+        "Variant Weight Unit",
+        "Variant Inventory Policy",
+        "Variant Fulfillment Service",
+        "Variant Requires Shipping",
+        "Variant Taxable",
+    ):
+        assert col in parsed.unknown_columns, col
+    assert "Variant Compare At Price" not in first
+
+
+# --- Detection robustness (review findings #1, #2): bias conservative ----------------
+
+
+def test_canonical_distinctive_column_vetoes_shopify_detection():
+    # A canonical file carrying a stray Shopify-signature name (`SEO Title`) stays
+    # canonical because it also has canonical-distinctive columns — no misparse,
+    # no dropped Type, no corrupted weight unit (review finding #2).
+    header = ["Handle", "Title", "Type", "Variant Weight", "Variant Weight Unit", "SEO Title"]
+    assert is_shopify_header(header) is False
+
+
+def test_dual_named_file_stays_canonical_and_warns_shopify_name():
+    # A malformed file with BOTH `Body (HTML)` and canonical `Description`: the
+    # canonical column vetoes detection, so `Body (HTML)` is honestly warned as an
+    # unknown column rather than silently shadowing `Description` (review finding #1).
+    data = (
+        b"Handle,Title,Body (HTML),Description,Variant Price\n"
+        b"mug,Moon Mug,FROM_BODY,FROM_DESC,18.00\n"
+    )
+    parsed = parse_csv(data)
+    assert parsed.dialect == "canonical"
+    assert parsed.rows[0].cells["Description"] == "FROM_DESC"
+    assert "Body (HTML)" in parsed.unknown_columns
+
+
+def test_real_shopify_export_still_detected():
+    # The conservative veto must not break a genuine Shopify export (no canonical-
+    # distinctive columns present).
+    parsed = parse_csv(_FIXTURE.read_bytes())
+    assert parsed.dialect == "shopify"
+
+
+def test_shopify_grams_clear_clears_weight_unit_together():
+    # An empty Variant Grams (a clear) clears the synthesized unit too — weight and
+    # unit move together, never a stale unit (review finding #3).
+    data = b"Handle,Title,Body (HTML),Variant Grams\nmug,Moon Mug,<p>x</p>,\n"
+    parsed = parse_csv(data)
+    assert parsed.dialect == "shopify"
+    cells = parsed.rows[0].cells
+    assert cells["Variant Weight"] == ""
+    assert cells["Variant Weight Unit"] == ""

backend/tests/test_products_endpoints.py

@@ -95,6 +95,17 @@ def test_sample_csv_imports_clean(fresh_db_url):
         assert body["summary"]["errors"] == 0 and body["summary"]["adds"] == 2
 
 
+def test_columns_md_served(fresh_db_url):
+    """DOC-2 column reference is app-served, unauthenticated documentation (§6.4)."""
+    with TestClient(create_app(database_url=fresh_db_url)) as client:
+        resp = client.get("/api/products/columns.md")
+        assert resp.status_code == 200
+        assert "text/markdown" in resp.headers["content-type"]
+        body = resp.text
+        assert "Body (HTML)" in body  # Shopify dialect notes present
+        assert "`Handle`" in body  # canonical columns present
+
+
 def test_export_returns_canonical_csv(fresh_db_url):
     with _merchant_client(fresh_db_url) as client:
         draft = _upload(client).json()

backend/tests/test_products_invariants.py

@@ -77,3 +77,25 @@ def test_apply_failure_rolls_back_whole_transaction_tel6(migrated_conn, monkeypa
     assert migrated_conn.execute("SELECT count(*) FROM import_draft").fetchone()[0] == 1
     events = [json.loads(r.message) for r in caplog.records if r.name == "ecomm.telemetry"]
     assert any(e["event"] == "import_apply_failed" and e["error_class"] == "RuntimeError" for e in events)
+
+
+# A partial Shopify export (signature: Body (HTML) + Variant Grams) naming only one
+# of the two existing products — INV-10 must hold across the dialect boundary.
+SHOPIFY_PARTIAL = (
+    b"Handle,Title,Body (HTML),Variant Price,Variant Grams\n"
+    b"mug,Mug,<p>x</p>,12.00,180\n"
+)
+
+
+def test_inv10_shopify_partial_never_deletes(migrated_conn):
+    acct, sf = _merchant(migrated_conn)
+    _import(migrated_conn, acct, sf, CSV_A)
+    before = migrated_conn.execute("SELECT count(*) FROM product").fetchone()[0]
+    d = products.import_validate(migrated_conn, sf, acct, "shopify.csv", SHOPIFY_PARTIAL)
+    assert d["dialect"] == "shopify"
+    products.confirm_draft(migrated_conn, sf, acct, d["id"])
+    after = migrated_conn.execute("SELECT count(*) FROM product").fetchone()[0]
+    # INV-10: nothing deleted; the unmentioned 'tee' is untouched.
+    assert after >= before == 2
+    handles = {r[0] for r in migrated_conn.execute("SELECT handle FROM product").fetchall()}
+    assert {"mug", "tee"} <= handles

docs/products-domain.md

@@ -60,6 +60,47 @@ Option names live both in `CanonicalProduct.option_names` (the values) and in
 `fields{}` (the file-presence marker the diff needs for the absent-vs-clear
 distinction).
 
+## Dialects (INV-17, SLICE-8)
+
+A file is normalized to canonical names **at the codec boundary**, so every stage
+downstream of `parse_csv` (validate → diff → apply) is dialect-agnostic — it only
+ever sees canonical cells. Two dialects exist: `canonical` and `shopify`.
+
+`dialect_shopify.py` is the Shopify adapter and the source of truth for the
+mapping (mirrored by `tests/test_products_dialect_shopify.py` and
+`tests/fixtures/shopify-export.csv`):
+
+- **Detection** — `is_shopify_header()` returns `shopify` iff the header carries a
+  Shopify-only *signature* column (`Body (HTML)`, `Variant Grams`, `Cost per item`,
+  `Gift Card`, a `Google Shopping / …` column, …) **and no canonical-distinctive
+  column**. A canonical-distinctive name — one Shopify renames away (`Description`,
+  `Variant Cost`, `Variant Weight`, `Google Product Category`) or a canonical-only
+  column Shopify lacks (`Variant Volume`, `Variant Tax ID 1/2`, `Variant Position`) —
+  **vetoes** Shopify detection. Detection is by signature, not an exact header set, so
+  extra market/region columns don't defeat it; the veto biases it conservative, because
+  under-detection is safe (Shopify-named columns are warned as not-imported) while
+  over-detection corrupts (canonical `Type` / `Variant Weight Unit` would be dropped).
+  So a hybrid or ambiguous header falls through to `canonical`, which maps shared
+  columns identically and warns the rest — it never misparses (§7.4).
+- **Mapping** — `map_shopify_header(header)` returns `(mapped, not_imported)`:
+  `mapped[i]` is the canonical name for column `i` (or `None` when it has no
+  canonical home), and `not_imported` is the warning list surfaced as the draft's
+  `unknown_columns`. The rule per column, in order: in `SHOPIFY_RENAME` →
+  canonical name; in `SHOPIFY_DROP` (`Type`, `Variant Weight Unit`) → not imported;
+  in `KNOWN_COLUMNS` → pass through; else → not imported (this last branch absorbs
+  the unbounded `… / <Market>` price columns without enumerating them).
+- **The two name-collision overrides** are why `SHOPIFY_DROP` exists: Shopify's
+  `Type` is a free-text category, but canonical `Type` is *structural*
+  (`standalone`/kits), so it is warned rather than folded in; and Shopify's
+  `Variant Weight Unit` is dropped because the `Variant Grams` → `Variant Weight`
+  rename is the weight source.
+- **The one value transform** lives in `parse_csv`: when a Shopify row has a mapped
+  `Variant Weight` (from `Variant Grams`), the codec synthesizes
+  `Variant Weight Unit = "g"`, since Shopify grams are unitless integers.
+
+`detect_dialect()` in `codec.py` is the INV-17 seam; a new dialect is a new adapter
+module plus a branch there, with no change to validate/diff/apply.
+
 ## Error granularity
 
 `validate.py` never raises on a row problem: every violation is recorded as a

e2e/fixtures/shopify-export.csv

@@ -0,0 +1,2 @@
+Handle,Title,Body (HTML),Vendor,Type,Tags,Published,Status,Variant SKU,Variant Grams,Variant Inventory Qty,Variant Price,Variant Compare At Price,Gift Card,SEO Title,Cost per item
+shopify-mug,Shopify Mug,<p>Imported from Shopify.</p>,Acme,Drinkware,"mugs",TRUE,active,SM-001,300,25,14.00,20.00,FALSE,Shopify Mug | Acme,7.00

e2e/tests/import-shopify-dialect.spec.ts

@@ -0,0 +1,35 @@
+// DoD scenario e2e_import_shopify_dialect (SD-0002 §6.8, SLICE-8): a Shopify
+// product CSV imports directly (PUC-6). Upload an unmodified-shape Shopify export;
+// the preview recognizes the dialect ("Shopify product CSV — mapped"), lists the
+// columns with no canonical home as not-imported, and the import confirms and
+// completes — the run report card carrying the same dialect label.
+import { expect, test } from "@playwright/test";
+import { gotoProducts, signUpWithStorefront, uploadFixture } from "../helpers";
+
+test("e2e_import_shopify_dialect", async ({ page }) => {
+  await signUpWithStorefront(page);
+  await gotoProducts(page);
+
+  await uploadFixture(page, "shopify-export.csv");
+
+  // Preview (§5.4): the file name, the recognized dialect, and the not-imported band.
+  await expect(
+    page.getByRole("heading", { name: "Import preview — shopify-export.csv" }),
+  ).toBeVisible();
+  await expect(page.getByText("Shopify product CSV — mapped")).toBeVisible();
+  // The not-imported band lists Shopify columns with no canonical home. Assert a
+  // column that never appears in canonical diff detail, so the match is unambiguous.
+  await expect(page.getByText("Columns not imported")).toBeVisible();
+  await expect(page.getByText("Variant Compare At Price")).toBeVisible();
+  await expect(page.getByRole("button", { name: "1 to add" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "0 errors" })).toBeVisible();
+
+  // Consent gate (PUC-3): confirm the import.
+  await page.getByRole("button", { name: "Import 1 products" }).click();
+
+  // Run detail (§5.5): report card carries the same dialect label and completes.
+  await expect(page.getByRole("heading", { level: 1, name: "shopify-export.csv" })).toBeVisible();
+  await expect(page.getByText("Shopify product CSV — mapped")).toBeVisible();
+  await expect(page.getByText("1 added · 0 updated · 0 rows in error")).toBeVisible();
+  await expect(page.getByText("Complete", { exact: true })).toBeVisible();
+});

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "wiggleverse-ecomm-frontend",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "wiggleverse-ecomm-frontend",
-      "version": "0.7.0",
+      "version": "0.8.0",
       "dependencies": {
         "react": "^18.3.1",
         "react-dom": "^18.3.1"

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wiggleverse-ecomm-frontend",
   "private": true,
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

frontend/src/productsApi.dialect.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { dialectLabel } from "./productsApi";
+
+describe("dialectLabel", () => {
+  it("labels canonical", () => expect(dialectLabel("canonical")).toBe("Canonical format"));
+  it("labels shopify as mapped (PUC-6)", () =>
+    expect(dialectLabel("shopify")).toBe("Shopify product CSV — mapped"));
+  it("passes through an unknown dialect verbatim", () =>
+    expect(dialectLabel("weird")).toBe("weird"));
+});

frontend/src/productsApi.ts

@@ -50,7 +50,9 @@ export type Result<T> = { ok: true; value: T } | { ok: false; error: ApiError; s
 
 // One label rule for CSV dialects, shared by Products history / preview / run detail.
 export function dialectLabel(d: string): string {
-  return d === "canonical" ? "Canonical format" : d;
+  if (d === "canonical") return "Canonical format";
+  if (d === "shopify") return "Shopify product CSV — mapped";
+  return d;
 }
 
 export type ExportStatus = "all" | "active" | "draft" | "archived";

frontend/src/screens/products/ImportUpload.tsx

@@ -50,9 +50,13 @@ export default function ImportUpload() {
         <span className="note">CSV, up to 5,000 rows</span>
       </label>
       <p className="note">
-        Works with the canonical format.{" "}
+        Works with the canonical format or a Shopify product CSV.{" "}
         <a href="/api/products/sample.csv" download>
           Download sample CSV
+        </a>{" "}
+        ·{" "}
+        <a href="/api/products/columns.md" target="_blank" rel="noopener">
+          Column reference
         </a>
       </p>
     </div>

frontend/src/screens/products/ProductsPage.tsx

@@ -113,6 +113,10 @@ export default function ProductsPage() {
           <p className="note">
             <a href="/api/products/sample.csv" download>
               Download sample CSV
+            </a>{" "}
+            ·{" "}
+            <a href="/api/products/columns.md" target="_blank" rel="noopener">
+              Column reference
             </a>
           </p>
         </div>