cost-handoff: README documenting the DTD-B decoupled architecture (Mac2 fetch → validated prod ingest)

7c4e1121d4888d9e1234130d7de47e4496b865e6 · 2026-06-11 19:57:18 -0700 · SteveStudio2
Files touched

A shopify/scripts/cost-handoff/README.md
Diff

commit 7c4e1121d4888d9e1234130d7de47e4496b865e6
Author: SteveStudio2 <stevestudio2@SteveStacStudio.lan>
Date:   Thu Jun 11 19:57:18 2026 -0700

    cost-handoff: README documenting the DTD-B decoupled architecture (Mac2 fetch → validated prod ingest)
---
 shopify/scripts/cost-handoff/README.md | 58 ++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/shopify/scripts/cost-handoff/README.md b/shopify/scripts/cost-handoff/README.md
new file mode 100644
index 00000000..7f0eff5f
--- /dev/null
+++ b/shopify/scripts/cost-handoff/README.md
@@ -0,0 +1,58 @@
+# Schumacher cost/link handoff — Mac2 → Kamatera prod (DTD-B decoupled)
+
+Delivers Schumacher **net cost** and **shopify_product_id links** from Mac2 into the
+canonical prod `dw_unified` on Kamatera, **without** Mac2 ever writing prod directly.
+
+## Why this exists (the architecture, the hard way)
+- **Canonical `dw_unified` lives on Kamatera** (always-on). The live pipeline — **Full Monte**
+  (8-phase enrich + Shopify push), the `shopify_api_queue` worker, vendor scrapers — all run
+  there. Mac2 is a workstation (sleeps/reboots); it is **not** a source of truth.
+- **But the Schumacher fetch must run on Mac2**: schumacher.com's CloudFront WAF **blocks
+  Kamatera's datacenter IP** (403). Mac2's residential-ish IP works, and the trade JWT +
+  Browserbase login refresh are Mac2-resident.
+- So: **fetch on Mac2, deliver to prod.** Writing straight to prod from a laptop (open tunnel
+  + prod creds on a workstation, no validation seam) was rejected by a unanimous DTD panel in
+  favor of the **decoupled, queue-style handoff** below — mirroring how `shopify_api_queue`
+  already works (stage → validated drain).
+
+## Flow
+```
+Mac2 schu-api-recrawl.js  (fetch cost, Mac2-local)
+   │  cost → schumacher_catalog.cost   (Mac2 working copy)
+   ▼
+*-export.sh   → CSV in ./out/                 (cost: mfr_sku,cost,discontinued ; links: mfr_sku,shopify_product_id)
+   ▼
+*-push.sh     → atomic scp to Kamatera         (.part then rename; ingester never reads a half-file)
+   ▼   staging/ (cost) · link-staging/ (links)
+*-ingest.js   → on KAMATERA: validate → transactional apply → move to applied/ (or rejected/)
+   ▼
+prod schumacher_catalog.cost / .shopify_product_id   → Full Monte prices + pushes
+```
+
+## Components
+| file | host | what |
+|------|------|------|
+| `schu-cost-export.sh` | Mac2 | dump local cost → `out/schu-cost-<UTC>.csv` |
+| `schu-cost-push.sh`   | Mac2 | atomic scp to `…/cost-ingest/staging/` |
+| `schu-cost-ingest.js` | Kamatera | validate + apply cost (default APPLIES; `--dry` to preview) |
+| `schu-link-export.sh` | Mac2 | dump local links (normalized numeric) → CSV |
+| `schu-link-push.sh`   | Mac2 | atomic scp to `…/cost-ingest/link-staging/` |
+| `schu-link-ingest.js` | Kamatera | fill **empty** links only (default `--dry`; `--commit` to apply) |
+
+## Safety gates (both ingesters)
+- min rows; numeric/range checks; **SKU must already exist** (no inserts)
+- **never zeroes a cost / never nulls a link**; link ingester **fills empty only** (never clobbers prod)
+- **max-fraction tripwire** (refuse a run touching >95% of the table)
+- one transaction → any error = full ROLLBACK + file → `rejected/`; idempotent (`IS DISTINCT FROM`)
+
+## The dup-guard (why links matter)
+Prod with cost-but-no-link treats already-created products as **net-new** → Full Monte would
+**duplicate** them. Before re-enabling Schumacher's Shopify push, the links must be on prod.
+Current guard: `vendor_registry.skip_shopify=true` on Schumacher (set 2026-06-11) blocks the
+push until links are propagated. Re-enable steps are queued in
+`~/.claude/yolo-queue/pending-approval/schumacher-relink-and-reenable.md`.
+
+## Status (2026-06-11/12)
+- Cost handoff: **APPLIED** — 4,040 Schumacher costs live on prod.
+- Link handoff: **built + dry-run** (would fill 471, keep 1,561, 0 unknown) — apply is **gated**.
+- All prod writes are Steve-gated; nothing here runs unattended except `--dry`.
← c90065ca Part 2 twin: Schumacher dw_sku→shopify_product_id LINK hando · back to Designer Wallcoverings · Monitor uses 2026 authoritative pricing (kravet_authoritativ 4b00794e →