No findings. This ASN passes all checks.
"
+ body = ""
+ for f in result.sorted_findings():
+ fill, text, label = _SEV_STYLE[f.severity]
+ fee = f"${f.fee:,.2f}/{esc(f.fee_per)}" if f.has_fee else "—"
+ body += (
+ f"Retailer-specific layer skipped — no "
+ "retailer resolved for this ASN; structural and field-level "
+ "rules only. Add the trading-partner id to partners "
+ "in engagement.yml.
")
+
+ return (f"
+
+
+ {esc(label)}
+ {n_ok} of {len(outcomes)} file(s) processed
+
+{sections}
+{limitations_html}
+{provenance.to_html()}
+"""
+
+
+def _report_text(config, outcomes: list[FileOutcome], provenance: Provenance) -> str:
+ lines = ["LAILARA LLC — EDI PRE-FLIGHT REPORT",
+ f"Client: {config.client_name} ({config.engagement_id})",
+ f"As of: {config.as_of_date.isoformat()}", "-" * 60]
+ for o in outcomes:
+ rl = _RETAILER_LABELS.get(o.retailer, "Unknown")
+ if o.status != "ok":
+ lines.append(f"{o.filename}: NOT PROCESSED — {o.error}")
+ elif o.doc_type == "850":
+ lines.append(f"{o.filename}: 850 PO {o.po.po_number} — "
+ f"{len(o.po.line_items)} line(s), ${o.po.total_amount:,.2f}")
+ else:
+ lines.append(f"{o.filename}: 856 ASN ({rl}) — "
+ f"{len(o.result.findings)} finding(s)")
+ lines.append("-" * 60)
+ lines.append(provenance.to_text())
+ return "\n".join(lines)
+
+
+def _css(draft: bool) -> str:
+ draft_css = (
+ ".ll-draft::before{content:'DRAFT';position:fixed;top:50%;left:50%;"
+ "transform:translate(-50%,-50%) rotate(-32deg);font-family:var(--s);"
+ "font-size:22vw;font-weight:700;color:rgba(204,16,10,.06);z-index:0;"
+ "pointer-events:none;white-space:nowrap}" if draft else ""
+ )
+ return f"""
+:root{{--s:{P.LL_SERIF};--f:{P.LL_SANS}}}
+*{{box-sizing:border-box}}
+body{{margin:0;background:{P.LL_CANVAS};color:{P.LL_TEXT};font-family:var(--f);line-height:1.6}}
+.ll-page{{position:relative;z-index:1;max-width:{P.LL_MAX_WIDTH};margin:0 auto;padding:48px 24px}}
+.ll-header{{border-bottom:1px solid {P.LL_GRIDLINE};padding-bottom:24px;margin-bottom:24px}}
+.ll-eyebrow{{font-size:12px;letter-spacing:.04em;text-transform:uppercase;color:{P.LL_RED};font-weight:600}}
+.ll-title{{font-family:var(--s);font-weight:700;color:{P.LL_INK};font-size:34px;margin:8px 0 16px}}
+.ll-client{{display:grid;grid-template-columns:repeat(auto-fit,minmax(160px,1fr));gap:8px 24px;font-size:14px}}
+.ll-k{{color:{P.LL_TEXT_SEC};font-size:11px;text-transform:uppercase;letter-spacing:.04em}}
+.ll-client .ll-k{{display:block}}
+.ll-banner{{border-radius:{P.LL_RADIUS};padding:16px 20px;margin-bottom:32px;display:flex;
+ justify-content:space-between;align-items:baseline;flex-wrap:wrap;gap:8px}}
+.ll-banner-status{{font-family:var(--s);font-weight:700;font-size:22px}}
+.ll-section{{margin:0 0 32px}}
+.ll-h2{{font-family:var(--s);font-weight:700;color:{P.LL_INK};font-size:22px;margin:0 0 8px;
+ padding-bottom:6px;border-bottom:1px solid {P.LL_GRIDLINE};word-break:break-all}}
+.ll-file-meta{{font-size:13px;color:{P.LL_TEXT_SEC};margin-bottom:12px}}
+.ll-file-error{{color:{P.LL_RED_DARK};background:{P.LL_RED_SURFACE};padding:10px 14px;border-radius:{P.LL_RADIUS}}}
+.ll-basis{{font-size:13px;color:{P.LL_TEXT_SEC};margin-top:10px}}
+.ll-clean-note{{background:{P.LL_HK_SURFACE};border-left:3px solid {P.LL_HK_DARK};padding:12px 16px;border-radius:{P.LL_RADIUS}}}
+.ll-table{{width:100%;border-collapse:collapse;font-size:14px}}
+.ll-table th{{text-align:left;background:{P.LL_CHICAGO};color:#fff;padding:8px 12px}}
+.ll-table td{{padding:8px 12px;border-bottom:1px solid {P.LL_GRIDLINE};vertical-align:top}}
+.ll-badge{{display:inline-block;font-size:11px;font-weight:600;text-transform:uppercase;
+ letter-spacing:.03em;padding:2px 8px;border-radius:{P.LL_RADIUS};white-space:nowrap}}
+.num{{text-align:right;font-variant-numeric:tabular-nums}}
+.ll-limitations{{margin:0;padding-left:20px}}
+.ll-limitations li{{margin-bottom:6px}}
+.ll-provenance{{margin-top:40px;background:{P.LL_CARD_BG};color:{P.LL_CARD_TEXT};padding:20px 24px;
+ border-radius:{P.LL_RADIUS};font-size:13px}}
+.ll-prov-title{{font-family:var(--s);font-weight:700;font-size:16px;margin-bottom:8px}}
+.ll-provenance div{{margin-bottom:4px;color:{P.LL_CARD_SUBTITLE}}}
+.ll-provenance strong{{color:{P.LL_CARD_TEXT}}}
+.ll-prov-inputs{{width:100%;border-collapse:collapse;margin-top:8px}}
+.ll-prov-inputs th{{text-align:left;border-bottom:1px solid rgba(255,255,255,.12);padding:4px 8px;color:{P.LL_CARD_MUTED}}}
+.ll-prov-inputs td{{padding:4px 8px;border-bottom:1px solid rgba(255,255,255,.08);color:{P.LL_CARD_SUBTITLE}}}
+.ll-prov-brand{{margin-top:12px;font-family:var(--s);color:{P.LL_CARD_MUTED}}}
+.mono{{font-family:ui-monospace,Consolas,monospace;font-size:12px;word-break:break-all}}
+{draft_css}
+@media print{{body{{background:#fff}}}}
+"""
+
+
+# --------------------------------------------------------------------------- #
+# Orchestration
+# --------------------------------------------------------------------------- #
+
+def _partner_map(config) -> dict:
+ partners = config.raw.get("partners") or config.basis.get("partners") or {}
+ return partners if isinstance(partners, dict) else {}
+
+
+def run(config_path: str, input_path: str, out_dir: str, *, final: bool = False) -> dict:
+ config = load_config(config_path)
+ partners = _partner_map(config)
+
+ files = _iter_input_files(input_path)
+ if not files:
+ raise SystemExit(f"no input files found at {input_path}")
+
+ outcomes = [_process_file(p, partners) for p in files]
+ n_ok = sum(1 for o in outcomes if o.status == "ok")
+ blocked = n_ok == 0
+
+ # Status: nothing usable -> failed; any error/unresolved -> warnings; else clean.
+ n_warn = sum(
+ 1 for o in outcomes
+ if o.status != "ok" or (o.doc_type == "856" and o.retailer_source == "unresolved")
+ )
+ if blocked:
+ status = "failed"
+ elif n_warn:
+ status = "warnings"
+ else:
+ status = "clean"
+
+ out = Path(out_dir)
+ out.mkdir(parents=True, exist_ok=True)
+
+ # The partner map now folds into config_hash (lailara_engagement >=0.2.1
+ # hashes extra top-level config blocks), so a change to it already moves the
+ # provenance hash. This surfaces the same fact human-readably in the footer.
+ extra = {}
+ if partners:
+ blob = repr(sorted((str(k), str(v)) for k, v in partners.items())).encode()
+ extra["partner_map"] = hashlib.sha256(blob).hexdigest()[:12]
+
+ provenance = build_provenance(
+ tool=TOOL, tool_version=TOOL_VERSION,
+ inputs=[o.input_ref for o in outcomes], config=config,
+ validation_status=validation_status_label(status, n_warn),
+ extra=extra,
+ )
+
+ html_path = out / "edi-preflight-report.html"
+ html_path.write_text(
+ _report_html(config, outcomes, provenance, draft=not final, blocked=blocked),
+ encoding="utf-8",
+ )
+ txt_path = out / "edi-preflight-report.txt"
+ txt_path.write_text(_report_text(config, outcomes, provenance), encoding="utf-8")
+
+ total_findings = sum(len(o.result.findings) for o in outcomes if o.result)
+ result = {
+ "status": "blocked" if blocked else "ok",
+ "report": str(html_path),
+ "txt": str(txt_path),
+ "n_files": len(outcomes),
+ "n_ok": n_ok,
+ "total_findings": total_findings,
+ "files": [
+ {"filename": o.filename, "doc_type": o.doc_type, "status": o.status,
+ "retailer": _RETAILER_LABELS.get(o.retailer, "Unknown"),
+ "retailer_source": o.retailer_source}
+ for o in outcomes
+ ],
+ }
+ if blocked:
+ result["readiness_report"] = str(html_path)
+ return result
+
+
+def main(argv=None) -> int:
+ ap = argparse.ArgumentParser(
+ prog="edi client mode",
+ description="Pre-flight a client's EDI file(s) in engagement mode.",
+ )
+ ap.add_argument("--config", required=True)
+ ap.add_argument("--input", required=True, help="an EDI file or a directory of them")
+ ap.add_argument("--out", default="client-output")
+ ap.add_argument("--final", action="store_true")
+ args = ap.parse_args(argv)
+
+ result = run(args.config, args.input, args.out, final=args.final)
+ if result["status"] == "blocked":
+ print(f"BLOCKED — no usable EDI. See {result['readiness_report']}")
+ return 3
+ print(f"processed {result['n_ok']}/{result['n_files']} file(s); "
+ f"{result['total_findings']} ASN finding(s)")
+ print(f"report -> {result['report']}\ntext -> {result['txt']}")
+ return 0
+
+
+if __name__ == "__main__": # pragma: no cover
+ raise SystemExit(main())
diff --git a/engagement.demo.yml b/engagement.demo.yml
new file mode 100644
index 0000000..d26da46
--- /dev/null
+++ b/engagement.demo.yml
@@ -0,0 +1,14 @@
+# Demo engagement config (safe to deploy: demo: true).
+client:
+ name: "Cinderhaven Provisions (demo)"
+engagement:
+ id: "DEMO-EDI-001"
+as_of_date: "2026-05-10"
+prepared_by: "Lailara LLC"
+demo: true
+# Partner-ID map: a client's trading-partner identifier (an ISA/GS sender or
+# receiver id, exact or case-insensitive substring) -> retailer ruleset. The
+# engine already recognizes the majors by name/DUNS, so this is only needed for
+# ids it can't infer. Keys: walmart | amazon | unfi | kehe | costco.
+partners:
+ "0078742099999": walmart # illustrative: a Walmart DC id not in the built-in table
diff --git a/scripts/engagement_guard.py b/scripts/engagement_guard.py
new file mode 100644
index 0000000..ec77677
--- /dev/null
+++ b/scripts/engagement_guard.py
@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""Lailara engagement deploy guard (Python, stdlib-only).
+
+Exit 2 if an ACTIVE (non-demo) client engagement.yml is present in the current
+directory. No-op otherwise, so demo builds and clean CI checkouts are unaffected.
+Self-contained (no dependency on the installed lailara_engagement package) so it can
+run in any repo's deploy/build environment.
+"""
+import os
+import re
+import sys
+
+for _f in ("engagement.yml", "engagement.yaml"):
+ if os.path.isfile(_f):
+ with open(_f, encoding="utf-8-sig") as _fh:
+ _txt = _fh.read()
+ if re.search(r"^\s*demo:\s*true\s*$", _txt, re.M):
+ continue # demo config -> safe
+ sys.stderr.write(
+ f"ENGAGEMENT GUARD: active client engagement config present ({_f}). "
+ "Client mode is runtime-only and must never deploy. Deactivate it "
+ "(set 'demo: true', or use engagement.demo.yml) before deploying.\n"
+ )
+ raise SystemExit(2)
+raise SystemExit(0)
diff --git a/scripts/git-hooks/pre-push b/scripts/git-hooks/pre-push
new file mode 100755
index 0000000..9be9de9
--- /dev/null
+++ b/scripts/git-hooks/pre-push
@@ -0,0 +1,24 @@
+#!/bin/sh
+# Lailara engagement deploy guard (git pre-push hook).
+#
+# Refuses to push while an ACTIVE (non-demo) client engagement.yml is present in
+# the working tree. Every tool repo auto-deploys on push, so blocking the push
+# blocks the deploy — client mode is runtime-only and must never ship.
+#
+# No-op when no engagement.yml exists (demo builds and clean CI checkouts push
+# normally), so demo behavior is unchanged.
+#
+# Activated per repo with: git config core.hooksPath scripts/git-hooks
+set -e
+for f in engagement.yml engagement.yaml; do
+ if [ -f "$f" ]; then
+ if grep -Eq '^[[:space:]]*demo:[[:space:]]*true[[:space:]]*$' "$f"; then
+ continue # demo config -> safe
+ fi
+ echo "ENGAGEMENT GUARD: active client engagement config present ($f)." >&2
+ echo "Client mode is runtime-only and must never deploy. Deactivate it" >&2
+ echo "(set 'demo: true', or remove/rename to engagement.demo.yml) before pushing." >&2
+ exit 2
+ fi
+done
+exit 0
diff --git a/tests/test_client_mode.py b/tests/test_client_mode.py
new file mode 100644
index 0000000..510b3d0
--- /dev/null
+++ b/tests/test_client_mode.py
@@ -0,0 +1,157 @@
+"""Client-mode tests for edi-preflight: intake, preflight, provenance report.
+
+Adversarial fixtures per checklist §6: unreadable/non-EDI input (blocked path),
+a clean ASN, a Latin-1-encoded file, partner-ID-map resolution of a retailer the
+engine can't auto-detect, and directory intake. Skipped if lailara_engagement
+isn't installed (as in the repo's default CI environment).
+"""
+
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("lailara_engagement")
+
+import client_mode # noqa: E402
+
+_SAMPLES = Path(__file__).resolve().parent.parent / "samples"
+
+_CONFIG = """
+client: {name: Meridian Farms}
+engagement: {id: MER-2026-08}
+as_of_date: 2026-05-10
+demo: true
+partners:
+ PARTNERX: walmart
+"""
+
+
+@pytest.fixture
+def cfg(tmp_path):
+ p = tmp_path / "engagement.demo.yml"
+ p.write_text(_CONFIG, encoding="utf-8")
+ return str(p)
+
+
+def _clean_856() -> str:
+ return (_SAMPLES / "walmart" / "856_clean.edi").read_text()
+
+
+def test_clean_856_reports_and_is_branded(cfg, tmp_path):
+ src = tmp_path / "asn.edi"
+ src.write_text(_clean_856(), encoding="utf-8")
+ out = str(tmp_path / "client-output")
+ result = client_mode.run(cfg, str(src), out)
+
+ assert result["status"] == "ok"
+ assert result["total_findings"] == 0 # 856_clean passes all checks
+ assert result["files"][0]["doc_type"] == "856"
+ assert result["files"][0]["retailer"] == "Walmart"
+ assert result["files"][0]["retailer_source"] == "auto"
+
+ html = Path(result["report"]).read_text(encoding="utf-8")
+ assert "Meridian Farms" in html # client header
+ assert "#f5f3ee" in html # branded warm canvas
+ assert "SHA-256" in html # provenance footer
+ assert "DRAFT" in html # draft watermark
+
+
+def test_non_edi_input_is_blocked(cfg, tmp_path):
+ src = tmp_path / "notes.txt"
+ src.write_text("this is not an EDI document\n", encoding="utf-8")
+ out = str(tmp_path / "out")
+ result = client_mode.run(cfg, str(src), out)
+
+ assert result["status"] == "blocked"
+ html = Path(result["readiness_report"]).read_text(encoding="utf-8")
+ assert "Data Readiness" in html # blocked -> readiness report
+ assert "notes.txt" in html # the offending file is named
+
+
+def test_latin1_encoded_file_is_read(cfg, tmp_path):
+ # A Latin-1 byte (the é in "Café") must not break intake — the reader falls
+ # back from UTF-8 to Latin-1 exactly as the web app does.
+ text = _clean_856().replace("Artisanal Sea Salt Crackers 12ct", "Café Crackers")
+ src = tmp_path / "latin1.edi"
+ src.write_bytes(text.encode("latin-1"))
+ out = str(tmp_path / "out")
+ result = client_mode.run(cfg, str(src), out)
+
+ assert result["status"] == "ok"
+ assert result["files"][0]["doc_type"] == "856"
+
+
+def test_partner_map_resolves_unknown_retailer(cfg, tmp_path):
+ # Swap the receiver id (ISA08 + GS03) to one the engine can't auto-detect;
+ # the partner map must still resolve it to the Walmart ruleset.
+ text = (_clean_856()
+ .replace("WALMART ", "PARTNERX ") # ISA08 (15-wide field)
+ .replace("*WALMART*", "*PARTNERX*")) # GS03
+ src = tmp_path / "asn.edi"
+ src.write_text(text, encoding="utf-8")
+ out = str(tmp_path / "out")
+ result = client_mode.run(cfg, str(src), out)
+
+ f = result["files"][0]
+ assert result["status"] == "ok"
+ assert f["retailer"] == "Walmart"
+ assert f["retailer_source"] == "partner-map"
+
+
+def test_unknown_retailer_without_map_falls_back_to_generic(tmp_path):
+ # Same swapped file, but a config with NO partner map: the retailer is
+ # unresolved and the retailer-specific layer is skipped (still processed).
+ cfg_no_partners = tmp_path / "cfg.yml"
+ cfg_no_partners.write_text(
+ "client: {name: X}\nengagement: {id: E1}\nas_of_date: 2026-05-10\ndemo: true\n",
+ encoding="utf-8",
+ )
+ text = (_clean_856()
+ .replace("WALMART ", "PARTNERX ")
+ .replace("*WALMART*", "*PARTNERX*"))
+ src = tmp_path / "asn.edi"
+ src.write_text(text, encoding="utf-8")
+ out = str(tmp_path / "out")
+ result = client_mode.run(str(cfg_no_partners), str(src), out)
+
+ assert result["status"] == "ok" # still processed
+ assert result["files"][0]["retailer_source"] == "unresolved"
+ html = Path(result["report"]).read_text(encoding="utf-8")
+ assert "retailer-specific layer skipped" in html.lower() or "unresolved" in html.lower()
+
+
+def test_directory_intake_processes_all_files(cfg, tmp_path):
+ d = tmp_path / "asns"
+ d.mkdir()
+ (d / "a.edi").write_text(_clean_856(), encoding="utf-8")
+ (d / "b.edi").write_text((_SAMPLES / "walmart" / "856_bad_dtm.edi").read_text(),
+ encoding="utf-8")
+ out = str(tmp_path / "out")
+ result = client_mode.run(cfg, str(d), out)
+
+ assert result["n_files"] == 2
+ assert result["n_ok"] == 2
+ assert result["total_findings"] == 4 # 856_clean (0) + 856_bad_dtm (4)
+
+
+def test_850_purchase_order_path(cfg, tmp_path):
+ src = tmp_path / "po.edi"
+ src.write_text((_SAMPLES / "walmart" / "850_with_allowances.edi").read_text(),
+ encoding="utf-8")
+ out = str(tmp_path / "out")
+ result = client_mode.run(cfg, str(src), out)
+
+ assert result["status"] == "ok"
+ assert result["files"][0]["doc_type"] == "850"
+ html = Path(result["report"]).read_text(encoding="utf-8")
+ assert "4500012400" in html # PO number in the 850 summary
+
+
+def test_final_flag_drops_watermark(cfg, tmp_path):
+ src = tmp_path / "asn.edi"
+ src.write_text(_clean_856(), encoding="utf-8")
+ out = str(tmp_path / "out")
+ result = client_mode.run(cfg, str(src), out, final=True)
+ html = Path(result["report"]).read_text(encoding="utf-8")
+ assert "ll-draft" not in html
+ assert "DRAFT" not in html
diff --git a/tests/test_demo_golden.py b/tests/test_demo_golden.py
new file mode 100644
index 0000000..ef2261d
--- /dev/null
+++ b/tests/test_demo_golden.py
@@ -0,0 +1,82 @@
+"""Demo golden-file lock for edi-preflight.
+
+Pins the engine output on the two files the deployed demo actually serves
+(``src.main._SAMPLE_FILES``) so the live site's demo experience cannot drift
+during the client-mode conversion. If either the served sample file or the
+engine changes what the demo shows, these tests fail on purpose.
+
+The 856 sample (``856_bad_dtm``) is deliberately chosen to exercise a
+chargeback-tier rule so the demo's "Est. Chargebacks" tile is non-empty; the
+850 sample (``850_with_allowances``) exercises header + line allowances. See
+the note in ``src/main.py`` next to ``_SAMPLE_FILES``.
+"""
+
+from collections import Counter
+
+from src.envelope import Retailer, parse_envelope
+from src.extract_850 import extract_850
+from src.main import _SAMPLE_FILES
+from src.validate_856 import validate_856
+from src.validate_856_walmart import validate_856_walmart
+from src.x12_tokenizer import tokenize
+
+
+def _load(doc_type: str) -> str:
+ return _SAMPLE_FILES[doc_type].read_text()
+
+
+class TestDemo856Golden:
+ """Locks the deployed 856 demo (walmart/856_bad_dtm.edi)."""
+
+ def test_sample_856_is_the_walmart_bad_dtm_file(self):
+ assert _SAMPLE_FILES["856"].name == "856_bad_dtm.edi"
+
+ def test_sample_856_findings_are_locked(self):
+ env = parse_envelope(tokenize(_load("856")))
+ assert env.retailer is Retailer.WALMART
+ result = validate_856_walmart(validate_856(env))
+ assert len(result.findings) == 4
+ by_severity = dict(Counter(f.severity.value for f in result.findings))
+ assert by_severity == {
+ "may-cause-chargeback": 3,
+ "will-cause-chargeback": 1,
+ }
+ assert sorted(f.rule_id for f in result.findings) == [
+ "invalid_bsn_date",
+ "invalid_dtm_date",
+ "invalid_dtm_date",
+ "invalid_sscc18_format",
+ ]
+
+ def test_sample_856_fee_breakdown_is_locked(self):
+ env = parse_envelope(tokenize(_load("856")))
+ result = validate_856_walmart(validate_856(env))
+ # One $1/case labeling defect; per-basis breakdown, never a cross-basis sum.
+ assert result.fee_breakdown == [
+ {"fee_per": "case", "count": 1, "subtotal": 1.0}
+ ]
+
+
+class TestDemo850Golden:
+ """Locks the deployed 850 demo (walmart/850_with_allowances.edi)."""
+
+ def test_sample_850_is_the_walmart_with_allowances_file(self):
+ assert _SAMPLE_FILES["850"].name == "850_with_allowances.edi"
+
+ def test_sample_850_extraction_is_locked(self):
+ env = parse_envelope(tokenize(_load("850")))
+ assert env.retailer is Retailer.WALMART
+ po = extract_850(env)
+ assert po.po_number == "4500012400"
+ assert po.po_type == "SA"
+ assert po.purpose_code == "00"
+ assert len(po.line_items) == 3
+ assert po.total_line_items == 3
+ assert po.total_quantity == 420.0
+ assert po.total_amount == 9329.7
+ assert len(po.header_allowances) == 2
+ assert len(po.all_allowances) == 6
+ assert [(a.entity_code, a.entity_name) for a in po.addresses] == [
+ ("ST", "WALMART RDC 7033"),
+ ("BT", "WALMART ACCOUNTS PAYABLE"),
+ ]