# Phase 20.2: Sync Integrity and Shipment State Fixes - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-04-13
**Phase:** 20.2-sync-integrity-and-shipment-state-fixes
**Areas discussed:** Shipment state derivation, Product creation durability, Image fetch + display timing, ww-card update scope

---

## Shipment State Derivation

| Option | Description | Selected |
|--------|-------------|----------|
| Use tracking events (Recommended) | Wire shopify_projection.rs into sync pipeline for real carrier states | |
| Fix the mapping in-place | Keep order-level fulfillment_status with corrected mapping | |
| Hybrid approach | Order-level baseline + tracking event overlay | |

**User's choice:** Custom — provided full card state machine with specific state names and cascade rules
**Notes:** States: Preparing (initial), Packing (label created), In Transit, Delivered (from carrier tracking on fulfillments), Return In Transit, Returned (from carrier states on reverse fulfillments). All states should also cascade to assigned serial units.

### Follow-up: Cascade behavior

| Option | Description | Selected |
|--------|-------------|----------|
| Auto-cascade all states (Recommended) | All card state changes auto-cascade to assigned serial units | ✓ |
| Cascade forward only | Only forward states cascade; returns only via explicit Start Return | |
| You decide | Claude picks | |

**User's choice:** Auto-cascade with important corrections
**Notes:** Serial units do NOT have a "Created" state. Cascade is product-aware: only units whose Shopify product is on the fulfillment (or units with no Shopify product) get the state change.

### Follow-up: Data migration

| Option | Description | Selected |
|--------|-------------|----------|
| Migrate in SQLite | Migration renames existing values | ✓ |
| Map at display time | Keep old values, translate in UI | |
| You decide | Claude picks | |

**User's choice:** Migrate in SQLite

---

## Product Creation Durability

| Option | Description | Selected |
|--------|-------------|----------|
| Immediate creation (Recommended) | Create ww-product GH Issue synchronously after SQLite insert | ✓ |
| Queue as pending edit | Local-first with pending edit queue | |
| You decide | Claude picks | |

**User's choice:** Immediate creation
**Notes:** User also emphatically corrected: serial units DO NOT have a "Created" state. Initial states are Available (unassigned) or Assigned (on a card).

---

## Image Fetch + Display Timing

| Option | Description | Selected |
|--------|-------------|----------|
| Immediate background fetch (Recommended) | Background task downloads image after product creation | |
| Next sync cycle | Image download during regular sync_products | |
| You decide | Claude picks | |

**User's choice:** User stated these bugs may be already fixed — card item squares already have image rendering, and Shopify image fetch may already work. Verify during research before planning fixes.

| Option | Description | Selected |
|--------|-------------|----------|
| Same as 20.1 D-08 pattern | Wire has-image/image-url with Image element | |
| You decide | Claude checks if 20.1 already fixed this | |

**User's choice:** Stated item squares already have image rendering — may be moot.

---

## ww-card Update Scope

| Option | Description | Selected |
|--------|-------------|----------|
| Update on every detected change (Recommended) | Queue pending edit for GH Issue body update on each diff | ✓ |
| Update on sync cycle only | Batch updates into sync cycle | |
| You decide | Claude picks | |

**User's choice:** Update on every detected change

---

## Claude's Discretion

- Exact fulfillment-to-state mapping implementation details
- How to match serial units to fulfillment line items by Shopify product
- SQLite migration strategy for "Packing" state addition
- PendingEdit type discriminator for ww-card body updates
- Whether reverse fulfillment tracking needs additional API calls

## Deferred Ideas

None — discussion stayed within phase scope.