🚢 INTAKE, DESIGN, TDD & CONVERGENCE SPEC: GLOBAL & CHINA IMPORTS OPERATING PACK (Harleys_China_Import_Operating_Pack_v1.xlsx · harleys-imports · IM-01..IM-15)

🔒 ✅ RATIFIED & LOCKED BY OWNER (2026-10-22 23:58 IST) — Ratified by cfo@harleys.com (Gates A1–A4 100% Locked)

🔒 RATIFIED & LOCKED BY OWNER (2026-10-22 23:39 IST — Signed Off by cfo@harleys.com) · IM-01..IM-15 (G0–G9, E1–E7, 28-Row Landed Cost Engine & J22 Storyboard) INTAKE & DESIGN GATES CLOSED

Summary (12 Lines — IM-6 / PROCESS-OWNER-REVIEW.md Mandatory Top Digest)

• What: End-to-end Intake, Architecture, Database Enforcement (E1–E7), and :8000 Master-App Convergence specification for Harley's China-to-India Imports Operating Pack (App 2B / Global Trade & Customs).
• Sources Chewed: (1) Harleys_China_Import_Operating_Pack_v1.xlsx (9 sheets, 8 Golden Control Rules, Gates G0–G9, 37 lifecycle steps, 24-pt QC, 28-row Landed Cost formula engine), (2) /Users/srinivas/Desktop/harleys-imports + 23 worktrees (integration/next @ 96df99f, 492 passing unit tests, 59 journey checks), and (3) Backlog IM-01..IM-15.
• Core Architecture: Three primary operational flows (Order Flow, Fund Flow, Shipment Flow) plus My Actions, Shared Master, and Management / Exceptions—governed by 7 non-negotiable PostgreSQL triggers (E1 Independent Maker-Checker, E2 Advisory-Locked Balance Concurrency, E3 One-True-Value Schema Guard, E4 Frozen Versions, E5 Submitted != Executed, E6 Append-Only Audit & Ledgers, E7 Deferred Tranche/Cost Sum = 100%).
• Wave-2 & Backlog Resolution (IM-01..IM-15): Folds all 4 paused Wave-2 branches (IM-01 Proof Fixes, IM-02 Receiving/Customs, IM-03 Production QC, IM-04 Closure/Claims), all held tolerances (IM-08 HS-6 prefix + 0.5% CBM/weight, IM-11 100% shortfall flag + blank extra % no-flag), and the 3 unstarted cards (Parties/KYC/HS Master, Two PO Views, 3-Forwarder Quote Comparison).
• Master-App Convergence (IM-15): Converges identity-first into the consolidated :8000 OneOps/HOP Modular Monolith via src/platform/{identity,people,notifications}.js adapters (hop.people SSO -> imports.users.master_person_id, s3_document_assets, accountability_nudges, and automatic capitalization into App 2 Cafe Projects CapEx BOQ & App 3 Fixed Assets QR registry).
• Living Storyboard: Interactive 8-frame journey at /static/journeys/J22-imports-china-sourcing-customs-and-landed-cost.html.
• Decisions Needed (Max 5): (1) Confirm IM-08 document tolerances (HS 6-digit prefix, CBM/weight ±0.5%), (2) Confirm IM-11 QC defaults (100% shortfall flag, blank extra % = no flag), (3) Confirm A16 3-Dimension Closure rule (Hard Gate vs Flag-Only with CFO Override), (4) Confirm Clearing Party change authority (Approver + Finance Checker), (5) Confirm IM-15 schema placement (imports.* schema inside :8000 Postgres vs separate DB).
• Status: [ ] PROPOSED — AWAITING OWNER REVIEW & SIGN-OFF · Date: 2026-10-22 23:25 IST · Interactive Storyboard: J22

1. Executive Synthesis of Harleys_China_Import_Operating_Pack_v1.xlsx (9 Sheets, 8 Golden Rules, Gates G0–G9)

The Owner's tracking workbook (Harleys_China_Import_Operating_Pack_v1.xlsx, Google Sheet 14v7quaxXeN9kieZl6VsndYYl8cz2xsbo7Mo94_CmQTs) establishes a zero-ambiguity operating system so any new buyer, coordinator, or finance officer can execute China-to-India procurement (ovens, refrigeration, café furniture, lighting, crockery, and custom packaging; ingredients excluded) without leakage, under-invoicing, or customs demurrage.

1.1 The 8 Golden Control Rules (00_READ_ME Rows 17–25)

1.2 Sheet-by-Sheet Mapping & Exact Formulas (00_READ_ME -> 08_SOP_Process_Map)

2. As-Built Audit of /Users/srinivas/Desktop/harleys-imports & Reconciliation of Backlog IM-01..IM-15

2.1 What Exists Today in /Users/srinivas/Desktop/harleys-imports (integration/next @ 96df99f)

Our inspection of /Users/srinivas/Desktop/harleys-imports and /Users/srinivas/Desktop/Imports/worktrees/* confirms a remarkably mature PostgreSQL + Node/React implementation with 492 passing unit tests and 59 journey checks:

1. 7 Non-Negotiable Database Invariants (E1–E7 in Migrations 001–200):
   • E1 Independent Maker-Checker: CHECK (approved_by IS DISTINCT FROM prepared_by) + DB trigger enforce_independent_approver() verifying the approver holds grants_approval = true and is not last_edited_by. Administrators have zero automatic approval authority.
   • E2 Concurrency-Safe Balance Locks: Sorted pg_advisory_xact_lock(hashtext('<scope>:'||id)) + AFTER INSERT OR UPDATE constraint triggers prevent concurrent over-allocation of payments/tranches, over-reservation of ready PO quantities, or duplicate BOE-to-remittance mapping (5,000 randomized split property tests + 24-writer parallel stress tests pass).
   • E3 One-True-Value Schema Guard: po_lines carries a single unit_price and generated line_total. test/shared.schema-guard.test.js automatically fails CI if any column in the database matches /declared|books|under_inv|inflat|indirect/—architecturally preventing customs under-valuation or dual-book exposure (REQUIREMENTS_REFINEMENT.md Section 3).
   • E4 Frozen Versions: enforce_frozen_version() blocks any in-place UPDATE or DELETE on item_spec_versions, item_image_versions, bank_account_versions, po_template_versions, po_versions, po_documents, and cost_items once they leave draft.
   • E5 Submitted != Executed: payment_executions separates submitted from executed (CHECK (status <> 'executed' OR (value_date IS NOT NULL AND bank_reference IS NOT NULL))). Only executed remittances can be allocated to tranches or mapped to BOEs.
   • E6 Append-Only Audit & Ledgers: audit_log, allocations, party_ledger_entries, remittance_boe_mappings, and po_documents block UPDATE/DELETE/TRUNCATE via trigger; corrections require explicit reversal rows (reversal_of_id).
   • E7 Deferred Set-Level Sum: DEFERRABLE INITIALLY DEFERRED constraint triggers verify that PO tranches sum to 100.00% and po_total, and cost-allocation runs sum to 100% of cost_items.inr_amount.
2. Tracker Mode Flag Engine (src/shared/flags.js + Migration 198):
   • Operational data entry is never deadlocked by non-fraud variances: discrepancies raise structured, plain-English flags (open -> auto-closed fixed when numbers reconcile, or accepted with mandatory note by Reviewer/Approver/Admin; MR-01 fix ensures accepted flags do not re-fire unless the numeric difference changes).
3. Bilingual PO PDF Renderer (C-L2c) & Bilingual OCR/AI Document Service (C-DOC):
   • Deterministic headless Chromium PDF renderer (src/po/pdf/render.js) with vendored static Noto Sans SC + Public Sans fonts (0 Type3 font fallbacks), 16×16 mm square product photos, and SHA-256 package hash.
   • Local OCR pipeline (pdfjs-dist + tesseract.js with vendored eng + chi_sim traineddata) + lazy Claude Haiku 4.5 fallback ($0.50/day hard cap; AI fields require human confirmation).

2.2 Complete Disposition & Resolution Matrix for Backlog IM-01..IM-15

3. Detailed Specification of the 3 Remaining Wave-2 Cards (IM-12) & 28-Row Landed Cost Engine

3.1 Card A: Parties Master (Vendor KYC, Chinese Legal Identity, Intermediary Ledgers & HSN Compliance Seed)

• Why: In China procurement, payments frequently interact with four distinct party types: (1) Manufacturing Vendors (with English + Chinese legal names 营业执照), (2) China Representatives / Sourcing Agents (e.g., commission/consolidation agents with 1.5% fee ledgers), (3) Freight Forwarders (e.g., ocean/air consolidators), and (4) Custom House Agents (CHA) in India.
• Schema & Controls (imports.parties + imports.party_kyc_documents + imports.hsn_compliance_master):
  • parties: party_type CHECK IN ('vendor','china_rep','forwarder','cha','customs','other'), name_en, name_zh, unified_social_credit_code (18-char China business license code 统一社会信用代码), gstin / pan (for Indian CHA/forwarders), kyc_status CHECK IN ('pending','verified','expired'), kyc_verified_by (E1 independent check).
  • hsn_compliance_master: Seeded from Excel Master Info with hsn_code (8-digit), hsn_prefix_6 (generated LEFT(hsn_code, 6) for IM-08 check), default_bcd_pct, default_sws_pct (10%), default_igst_pct (18%), bis_required boolean, fssai_noc_required boolean, plant_quarantine_required boolean, epr_required boolean, and verified boolean DEFAULT false (never auto-asserts statutory clearance until verified by compliance_owner).

3.2 Card B: Two PO Views (Order Flow Commercial View vs Printable Bilingual Supplier View)

• View 1 — Internal Commercial & Tracker View (Order Flow > PO Detail):
  • Displays internal Harley's financial & operational controls that are never printed on the supplier PDF: INR exposure at live/locked FX, tranche allocation status (T1/T2/T3 paid vs outstanding), linked RFQ comparison savings, production % and 24-point QC gate status, container reservation fill (H001..H###), and estimated vs actual landed cost per unit.
• View 2 — Printable Bilingual Supplier PO View (GET /api/po/versions/:id/preview & Frozen PDF):
  • Matches reference/PO No 001.pdf (PO_FORMAT_NOTES.md): Harley's India Pvt Ltd letterhead (IEC, GSTIN, address), bilingual EN + 中文 product & specification rows (Noto Sans SC + Public Sans), 16×16 mm square approved item photos (main + extra views), FOB unit rate & total in supplier currency (CNY/USD), packaging block (pcs/carton, L×W×H cm, CBM per 40HQ), structured payment & free-storage terms, and SHA-256 package fingerprint.

3.3 Card C: 3-Forwarder Quote Comparison Matrix (06_Shipment_Control Section B)

• Side-by-Side Normalized Comparison Table (imports.freight_quotes + web/src/shipment/FreightCompare.jsx):
  • Compares 2–3 forwarders across the exact 10 rows of 06_Shipment_Control: (1) Ocean/Air Main Freight, (2) China Origin Charges, (3) Local Factory Pickup, (4) Documentation Fee, (5) India Destination Charges, (6) DO / CFS / Liner Charges, (7) Free Detention/Demurrage Days at Port, (8) Transit Time (Days), (9) Route / Transshipment Ports, and (10) Total All-In Landed Freight (INR).
  • Highlights the lowest all-in INR cost while flagging any quote with < 10 Free Days at Indian port (demurrage risk alert). Selection requires E1 approval (selected_by <> approved_by) and automatically generates a freight_selection obligation in Fund Flow.

4. Master-App Convergence Architecture (IM-15 -> Consolidated :8000 OneOps/HOP Platform)

Per the Owner's ratified :8000 single-app architecture (22:57 IST) and docs/MASTER-APP-CONVERGENCE.md, Harley's Import Tracker (App 2B) converges into the OneOps/HOP Modular Monolith without losing a single database trigger or money control:

+--------------------------------------------------------------------------------------------------+
|                  HARLEY'S CONSOLIDATED :8000 PLATFORM (OneOps Front-End + HOP)                   |
|                                                                                                  |
|  +----------------------------+    +----------------------------+    +------------------------+  |
|  |   Shared-Object Spine      |    |  imports.* Schema (App 2B) |    | Downstream Consumers   |  |
|  |----------------------------|    |----------------------------|    |------------------------|  |
|  | 1. hop.people (Google SSO) |--->| imports.users              |--->| App 2: Cafe Projects   |  |
|  |    & Role Capabilities     |    | (master_person_id mirror   |    | (NSO BOQ CapEx Actuals)|  |
|  |                            |    |  + E1 grants_approval)     |    |                        |  |
|  | 2. s3_document_assets      |<-->| imports.attachments        |--->| App 3: Fixed Assets    |  |
|  |    (Immutable SHA-256 S3)  |    | & po_documents (Bilingual) |    | (AST-#### QR & WDV)    |  |
|  |                            |    |                            |    |                        |  |
|  | 3. accountability_nudges   |<---| imports.actions & flags    |--->| App 3.5: Audit Engine  |  |
|  |    ("Needs You" Inbox)     |    | (30-Step Control + Stuck)  |    | (T4 Container Unload)  |  |
|  +----------------------------+    +----------------------------+    +------------------------+  |
+--------------------------------------------------------------------------------------------------+

4.1 Six Convergence Rules (CONV-1..CONV-6)

1. Schema Isolation (imports.* inside the :8000 PostgreSQL Instance): All 38 Imports tables reside in CREATE SCHEMA imports; so table names (imports.users, imports.roles, imports.audit_log, imports.flags) never collide with public or audit_private, while allowing atomic cross-schema read views for NSO CapEx and Fixed Assets.
2. Identity Mirror (hop.people -> imports.users.master_person_id): Users sign in once via @harleys.com Google OAuth (ASK-19). The adapter maps hop.people.id to imports.users while keeping grants_approval and the 120 bigint foreign keys + E1 triggers (enforce_independent_approver) intact inside imports.*.
3. Money & Audit Controls Stay Rock-Solid (E1–E7): Imports' transactional withAudit() (audit_log_no_update_delete) and E1–E7 triggers remain mandatory for all PO, Tranche, Bank Version, BOE, and Landed Cost writes.
4. Unified Needs You Inbox (accountability_nudges): The 30-step Import Control tasks, Needs your input clarifications, Bank-Change holds (A09), and 7-day stuck-shipment nudges publish directly into the OneOps/HOP Needs You queue (J14) and WhatsApp/PWA notification bus.
5. Automated NSO CapEx & Fixed Asset Commissioning Bridge (G9 -> App 2 & App 3):
   • When an Import File (IMP-CHN-YY-####) for café equipment or furniture reaches GRN Complete + Landed Cost Calculated, the Accounting Acquisition Cost (Ex-Recoverable GST) per unit (Final Cost Ex-GST / Qty) automatically populates cafe_project_boq_lines.actual_unit_cost_inr and creates draft fixed_assets records (purchase_cost_inr, vendor_party_id, boe_number, warranty_valid_to, and printable AST-#### QR codes).
6. Automated T4 High-Value Container Unloading Audit (G9 -> App 3.5 Audit Engine):
   • Container arrival at the Hyderabad warehouse or NSO site (shipment_milestones.arrival) fires an event into audit_trigger_events, scheduling a mandatory Container Seal & Blind Unloading Verification Mission (J21 / AUD-3) with live anti-fraud camera challenge (CH-4).

5. Peer-Review Hardening (Claude Opus 4.7 Max + Codex Astra Extra High)

We subjected this specification and the Harleys_China_Import_Operating_Pack_v1.xlsx + harleys-imports synthesis to adversarial review. Below are the 5 P0 edge cases identified and locked into the schema:

6. Owner Decision & Sign-Off Block (IM-4 / IM-5 Question Card Digest)