Space deploy v5: orphan snapshot of main, zero binary files

Hugging Face now rejects any push whose history carries binaries outside Xet
storage, and it scans the whole history, not the tip. v4 deleted the heavy
files in its final commit but still carried them across 70 ancestors, so the
pre-receive hook declined it.

This is the same shape as the v3 deploy branch: a single orphan commit holding
one snapshot of the tree, with every png/jpg/pdf/docx dropped and the README
image embeds replaced by pointers to the GitHub repo. Only favicon.ico stays,
which HF accepted on v3.

Content equals main at bb0f34a: real BPS data, quota and auth code, and the
out-of-coverage commodity reply.

.dockerignore

@@ -0,0 +1,50 @@
+# Keep the HF Spaces Docker image lean — only ship what runtime needs.
+#
+# Without this file, `COPY . .` in the Dockerfile drags in venv/ (~150 MB),
+# dashboard/node_modules, .git history, test caches, etc. — bloating the
+# image, slowing the build, and exposing local-only files inside the
+# container.
+
+# Python virtualenvs + caches
+venv/
+.venv/
+env/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Frontend (built/served separately on Vercel — not needed in the API image)
+dashboard/node_modules/
+dashboard/.next/
+dashboard/out/
+node_modules/
+
+# VCS + IDE
+.git/
+.gitignore
+.github/
+.vscode/
+.idea/
+
+# Local docs/build artifacts that don't ship with the API
+docs/*.pdf
+docs/*.docx
+docs/generate_*.py
+
+# Secrets — must never enter the image (set via HF Space env vars instead)
+.env
+.env.*
+*.pem
+*.key
+
+# OS junk
+.DS_Store
+Thumbs.db
+
+# Dev-only directories (won't be exercised in the deployed image)
+benchmarks/
+examples/
+tests/

.github/workflows/test.yml

@@ -0,0 +1,69 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: pytest (${{ matrix.os }} · py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: requirements.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run pytest
+        run: pytest -q
+
+  benchmark:
+    name: latency benchmark (publish, no gate)
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run latency benchmark
+        run: python benchmarks/latency.py | tee benchmark_results.txt
+
+      - name: Upload benchmark artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: latency-benchmark-${{ github.sha }}
+          path: benchmark_results.txt
+          retention-days: 30

.gitignore

@@ -0,0 +1,158 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+.env
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.cache
+*.cover
+*.log
+
+# LaTeX build artifacts (never commit; .tex + .pdf are committed)
+*.aux
+*.out
+*.toc
+*.fls
+*.fdb_latexmk
+*.synctex.gz
+
+# Word lock files (when Word has docx open)
+~$*.docx
+~$*.xlsx
+~$*.pptx
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# OS
+.directory
+desktop.ini
+
+# Local configs
+*.local
+.env.local
+config.local.json
+
+# Claude Code project settings (local-only)
+.claude/
+
+# API keys / secrets (defensive — never commit)
+.secrets
+secrets/
+*.pem
+*.key
+api_keys.txt
+
+# Temporary extraction artifacts
+v8_extracted.txt
+v9_extracted.txt
+*_extracted.txt
+
+# Proposal docx files — internal team artifacts, not for public repo
+AgriFlow_v8.docx
+AgriFlow_v9.docx
+AgriFlow_v10.docx
+docs/AgriFlow_v8.docx
+docs/AgriFlow_v9.docx
+docs/AgriFlow_v10.docx
+docs/AgriFlow_v11.docx
+docs/AgriFlow_v12.docx
+docs/AgriFlow_v13.docx
+docs/AgriFlow_v13_clean.docx
+
+# Proposal docx generator scripts — internal toolchain, paired with the
+# gitignored .docx outputs above (kept consistent: if the artefact is private,
+# the script that builds it stays private too).
+docs/generate_v10_docx.py
+docs/generate_v11_docx.py
+
+# Internal audit notes (frank code↔doc consistency check; not for public repo)
+docs/AUDIT_v10.md
+
+# Proposal PDF intermediates (rendered from docx for wiki ingest)
+docs/AgriFlow_v8.pdf
+docs/AgriFlow_v9.pdf
+docs/AgriFlow_v10.pdf
+docs/AgriFlow_v11.pdf
+docs/AgriFlow_v12.pdf
+
+# Proposal opendataloader-pdf-converted markdown (derived from gitignored docx;
+# wiki copy lives at D:/Research/Project Data/k1/raw/documents/agriflow/).
+# Same privacy stance as the .docx originals — internal team artifact.
+docs/AgriFlow_v8.md
+docs/AgriFlow_v9.md
+docs/AgriFlow_v10.md
+docs/AgriFlow_v11.md
+docs/AgriFlow_v12.md
+
+# Local scratch space (experiments, transient logs, run trackers)
+.tmp/
+
+# Internal deployment notes — not for public repo
+DEPLOY.md
+DEPLOY_RENDER.md
+render.yaml.disabled
+
+# Internal data-acquisition guidelines — operational how-to, not for public repo
+*_GUIDE.md
+sample_data/bps_real/DATA_ACQUISITION_GUIDE.md
+
+# Draft/scratch READMEs — stale or redundant
+docs/README_v12_DRAFT.md
+
+# Handoff documents — session artifacts, internal only
+HANDOFF.md
+HANDOFF.pdf
+
+.vercel
+
+# TimesFM model cache — model is ~2GB, never commit
+# (model auto-downloads to HF cache dir on first run)
+~/.cache/huggingface/
+.cache/huggingface/
+timesfm_model_cache/
+
+# pip temp dirs (disk-full workaround)
+/d/pip-tmp/
+/d/pip-cache/
+
+# Dashboard-internal README — not for public repo
+dashboard/README.md
+
+# Local subscription/quota state (JSON quota backend)
+.state/

.python-version

@@ -0,0 +1 @@
+3.12.7

Dockerfile

@@ -0,0 +1,39 @@
+# Hugging Face Spaces — Docker SDK build for the AgriFlow FastAPI backend.
+#
+# Why this exists:
+#   HF Spaces (Docker SDK) builds + runs this container; the resulting public
+#   URL is what the Vercel dashboard hits via NEXT_PUBLIC_API_URL and what
+#   Twilio's WhatsApp Sandbox webhook points at.
+#
+# Port contract:
+#   HF Spaces expects the app to listen on 7860 by default. We honour that.
+#
+# Secrets (set in the Space's "Settings → Variables and secrets" UI, never here):
+#   GEMINI_API_KEY        — from aistudio.google.com
+#   TWILIO_ACCOUNT_SID    — Twilio console
+#   TWILIO_AUTH_TOKEN     — Twilio console
+#   TWILIO_WHATSAPP_FROM  — whatsapp:+14155238886 (sandbox) or your number
+#   MOCK_MODE=true        — start here; flip to false once Gemini/Twilio keys are set.
+
+FROM python:3.12-slim
+
+# Avoid stale .pyc + force unbuffered stdout for clean HF log streaming.
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PORT=7860
+
+WORKDIR /app
+
+# Install dependencies first so layer is cacheable when source changes.
+COPY requirements.txt ./
+RUN pip install --upgrade pip && pip install -r requirements.txt
+
+# Now copy the rest of the project.
+COPY . .
+
+# HF Spaces routes external traffic to this port.
+EXPOSE 7860
+
+# Same entrypoint Render would have used, just on port 7860 instead of $PORT.
+CMD ["uvicorn", "whatsapp_bot.server:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hilmi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.en.md

@@ -0,0 +1,212 @@
+Language / Bahasa: **English** · [Bahasa Indonesia](./README.md)
+
+<p align="center"><img src="assets/logo-mark.png" alt="AgriFlow logo" width="300"/></p>
+
+<h1 align="center">AgriFlow</h1>
+
+<p align="center">
+  <strong>AI-Powered Food Security Intelligence Platform</strong><br/>
+  <em>Inter-Regional Agricultural Supply–Demand Matching Platform</em>
+</p>
+
+<p align="center"><b>Detect · Predict · Distribute</b></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/PIDI-DIGDAYA%20%C3%97%20Hackathon%202026-1B5E20?style=for-the-badge" alt="Hackathon"/>
+  <img src="https://img.shields.io/badge/Problem%20Statement-2%20Matching%20Demand–Supply-4CAF50?style=for-the-badge" alt="PS"/>
+  <img src="https://img.shields.io/badge/tests-520%20passing-brightgreen?style=for-the-badge" alt="Tests"/>
+</p>
+
+> **Project roadmap spans 3 Phases.** Full technical documentation from previous versions is archived at [`README_v13.md`](README_v13.md) (latest snapshot), [`README_v12.md`](README_v12.md), and [`README_v11.md`](README_v11.md).
+
+---
+
+<details>
+<summary><b>🖼️ View Research Poster (click to expand)</b></summary>
+
+<br/>
+
+<p align="center"><img src="poster/agriflow-poster.jpg" alt="AgriFlow Research Poster" width="100%"/></p>
+
+</details>
+
+---
+
+# Phase 1 — Team & Links
+
+## Team
+
+| Name | Role | LinkedIn |
+|------|------|----------|
+| Chelsea | Data Analyst | [Chelsea](https://linkedin.com/in/chelseaayu) |
+| Hilmi | Data Architect | [Hilmi](https://linkedin.com/in/hilmi888/) |
+| Monika | UX Researcher | [Monika](https://linkedin.com/in/monika-hermiani) |
+| Irpan | Data Engineer | [Irpan](https://linkedin.com/in/irpanpilihanrambe) |
+
+## Links
+
+| Resource | Link |
+|----------|------|
+| Pitch Deck | [Canva](https://www.canva.com/design/DAHETj2ulzg/VIvgxVkQ6I9R24ucphy2mQ/view) |
+| Dashboard (Live Demo) | [agriflow-engine.vercel.app](https://agriflow-engine.vercel.app/) |
+| Proposal (v13) | [docs/AgriFlow_Proposal_v13.pdf](docs/AgriFlow_Proposal_v13.pdf) |
+
+---
+
+# Phase 2 — What We Have Built (MVP)
+
+## The Problem
+
+Every year Indonesia loses trillions of rupiah in food — **40% occurs in distribution, not production**. In one district farmers throw away chilli because prices collapse; in the next district prices spike because supply is scarce. Local governments often discover the crisis **2–3 weeks too late**.
+
+## The Solution
+
+**AgriFlow matches surplus districts with deficit districts** — like "Uber for food", but aware of perishability, real road distances, and **equity for underserved regions**. Three core functions:
+
+- **Detect** — find price anomalies (spikes/drops) from daily price data.
+- **Predict** — forecast prices 30 days ahead.
+- **Distribute** — intelligently and equitably match surplus to deficit.
+
+## Architecture (High-Level)
+
+```
+   REAL DATA SOURCES             AGRIFLOW ENGINE                   ACCESS
+  (BPS · PIHPS · OSRM)      ┌──────────────────────────┐
+  production · consumption ─▶│ DETECT   price anomalies  │ ──┐
+  prices · population        │ PREDICT  30-day forecast  │   ├──▶ Map dashboard
+  per-district East Java     │ DISTRIBUTE 4-layer match  │   └──▶ WhatsApp bot
+                             └──────────────────────────┘
+```
+
+All three functions (Detect · Predict · Distribute) share one real data source, then served via Dashboard and WhatsApp.
+
+📄 **Full methodology detail — rationale, how it works, evaluation, validation, and paper citations: [Architecture Document (PDF)](docs/AgriFlow_Architecture.pdf).**
+
+## Features Already Running
+
+| Function | Feature | Status |
+|----------|---------|:------:|
+| **Distribute** | 4-layer matching engine (hard constraints → multi-objective scoring → equity) running on **real BPS per-district data (2022)** | ✅ |
+| **Detect** | Price anomaly detection (deseasonalize + robust statistics) on daily PIHPS prices **2021–2025** | ✅ |
+| **Predict** | 30-day price forecasting with **TimesFM 2.0** (time-series foundation model) | ✅ |
+| **Accessibility** | **WhatsApp Chatbot** (ask price & recommendations) + **interactive map Dashboard** | ✅ |
+| **Security** | The site is *login-first*: opening it shows a login page. Judges click **"Masuk sebagai Tamu" (Enter as Guest)** to review without creating an account. A Supabase account system (server-side JWT verification, Row Level Security on 12 tables, password reset) is ready for a subscription model; sensitive subscriber & billing data stays JWT-protected server-side. | ✅ |
+| **Real data** | **6 real commodities** per-district: premium & medium rice, large & cayenne chilli, red & garlic onion + 5 years of PIHPS prices | ✅ |
+
+> **Quality:** 520 automated tests pass (521 collected, 1 skipped) — the engine is tested, reproducible, and honest about its limitations (see [Testing & Scenarios](#testing--scenarios) and Phase 3).
+
+### Snapshots
+
+**Dashboard** — East Java map with per-district surplus/deficit bubbles, a *top matches* list, plus a **price Forecast & Anomaly** panel (all three functions on one screen):
+
+![AgriFlow Dashboard](assets/dashboard.png)
+
+**WhatsApp Bot** — ask prices, find buyers/suppliers, get price forecasts & anomalies via chat. Supports **Indonesian** and **Javanese** (inclusion for rural farmers):
+
+| Indonesian | Javanese |
+|:---:|:---:|
+| ![WhatsApp Indonesian](assets/whatsapp-id.png) | ![WhatsApp Javanese](assets/whatsapp-jawa.png) |
+
+## Testing & Scenarios
+
+Because AgriFlow's output drives inter-district food allocation that touches low-HDI districts, claims of "fair" and "robust" must be re-auditable — not just narrative. The test suite locks food-balance figures as *golden numbers* (reproducibility), guards sensitive policy parameters against accidental drift (regression-safety), and tests anomaly detection adversarially.
+
+**521 tests collected · 520 pass · 1 skipped · cross-OS on CI.**
+(Skip = `test_timesfm_importorskip`: skipped when the heavy TimesFM library isn't installed on the runner; the forecasting path is still tested via fallback + API contract.)
+
+The production server loads **real BPS data by default** (`DATA_BACKEND=csv`, the default). The old synthetic 19-commodity fixture is still used by 13 test files (`DATA_BACKEND=demo`) to exercise engine logic across a wider commodity range — it is never served to users.
+
+| Category | Count | Coverage |
+|---|---|---|
+| Per-layer unit (L0–L3) | 73 | IPM tier, distance/perishability constraints, scoring, equity allocation |
+| 24 edge-case scenarios (A–F) | 27+ | Volume, spatial, temporal, disruption, political, quality |
+| Real BPS/PIHPS data validation | 57 | Rice + horticulture 2022 food-balance, reproducible pipeline |
+| Price anomaly detection | 49 | Season-aware S-H-ESD on deseasonalized residuals |
+| Forecast & API | 40 | Forecast/anomaly endpoints + fallback |
+| Baseline & equity | 39 | greedy/uniform/proportional vs AgriFlow + supply-constrained scenario |
+| Ingest & integration | 73 | DB loader, PIHPS ingest, OSRM distance, WhatsApp bot |
+| Dashboard auth & WhatsApp quota | 117 | Supabase login, server-side JWT verification, RLS on 12 tables, password reset, WhatsApp free-tier quota (disabled by default) |
+
+The **24 edge-case scenarios** map to real East Java events, e.g.: Ramadan spike (C1), Mt. Semeru eruption in Lumajang → unreachable (D4), multi-district flood of rice belts (D5), fuel-price hike → higher logistics cost (E5), and Bulog contract-reserve priority (E3).
+
+**Key results:**
+- **Equity proven under scarcity, at zero efficiency cost.** *This is a hypothetical stress test, not a result from the real BPS data:* on the 2022 data East Java is in fact heavily in surplus (6.6× ratio), so the equity value would not surface. To show how the mechanism works we built a synthetic scarcity scenario (the `surplus_deficit_constrained.csv` fixture, surplus 3962t vs deficit 5249t). In it, pure greedy abandons Madura — Sampang **0%**, Bangkalan **20%**; AgriFlow lifts both to **100%** at *identical aggregate coverage* (0.6649), with Gini dropping (0.3017 → 0.2905). We do not claim an equity advantage under abundance, nor that this scenario comes from real data.
+- **Season-aware anomalies.** A ~60% price drop is flagged, but a pure seasonal pattern (pre-Eid cycle) does **not** trigger false positives; genuine anomalies riding on top of the seasonal pattern are still caught.
+- **The data reveals a structural deficit, not a bug.** Garlic (bawang putih) produces **0 matches** across all 38 districts on the 2022 BPS data — East Java is deficit in garlic in every district, consistent with Indonesia being a net garlic importer. The engine is working correctly; the data is what's speaking.
+
+📄 Full detail (why, the 24-scenario list, paper citations): [Architecture Document](docs/AgriFlow_Architecture.pdf) §Testing & Validation.
+
+## Why Our Tech Stack Is LEAN (not as large as the original proposal)?
+
+The initial proposal listed a large stack (Qdrant, LangChain, Redis, n8n, multi-cloud, etc.). After actually building, we **intentionally cut it** — *honest engineering* for current scale (38 districts in East Java):
+
+| Original Plan | What We Use | Reason |
+|---|---|---|
+| Qdrant (separate vector DB) | **Supabase pgvector** | Small corpus — no need for a dedicated vector service |
+| LangChain | **Gemini API directly** | RAG this simple doesn't need a heavy framework |
+| Redis cache | **In-process cache** | Load doesn't require it yet; engine is deterministic |
+| 5 hosting platforms | **2 (HF Spaces + Vercel)** | Fewer failure points, cheaper |
+
+**Our principle: use what's sufficient, not what's fashionable.** Big components earn their place when scale justifies them — that's **Phase 3**.
+
+---
+
+# Phase 3 — Future Plans & Scaling
+
+Phase 3 covers two things we keep honestly separate: features we intentionally deferred because they aren't needed at the current scale, and limits we've measured on the running engine and scheduled fixes for.
+
+## What's deferred (waiting on data or real load)
+
+| Plan | Purpose | Trigger |
+|---|---|---|
+| National scale, 514 districts | From 38 East Java districts to all of Indonesia | spatial partitioning + distance precompute |
+| Exogenous forecasting (ENSO index, Ramadan calendar) | Accuracy improves under climate shocks & holidays | exogenous data available |
+| Broiler chicken & eggs (real data) | Completes the 6 core commodities | per-district broiler & layer-egg production data released |
+| Granular per-city/market prices | Real gap can be Rp5,000 to 15,000/kg (chilli interview) | open market price feed |
+| Facilitating inter-district transactions | Price info alone is "not effective enough" without a buy/sell channel (onion & rice interviews) | distribution partnership |
+| Source transparency & transaction security | User-trust requirement (interviews) | formal partnership stage |
+| Sahabat-AI (Javanese/Madurese) + phone IVR | Inclusion for elderly farmers & feature-phone users | channel-scaling stage |
+| Qdrant / Redis / n8n | Vector scale, caching, orchestration | when real load arrives |
+
+## Coverage limits today (the gate is data availability, not architecture)
+
+The engine is already ready to process any data it's given; what limits it is the availability of public per-district data. Once a source opens up, the same pipeline processes it immediately with no architecture change.
+
+| Coverage today | The gate |
+|---|---|
+| 6 core commodities | awaiting per-district production data for other commodities to be released by BPS |
+| Reference year 2022 | the most complete year across all per-district sources; a newer year is simply ingested when available |
+| Broiler chicken & eggs not yet | the other 13 commodities remain synthetic placeholders, not served to users (`DATA_BACKEND=csv`) |
+| Chilli/onion consumption via national figures | rice consumption is already per-district & used for real; the rest awaits publication |
+| Tier-2 prices (non-IHK districts) | Bapanas Panel Harga is under maintenance; once the feed is restored, 30+ districts are covered immediately |
+
+## Quantified engineering debt (scheduled fixes)
+
+We measured these two limits ourselves against the engine's own achievable ceiling, with benchmarks committed and reproducible by a judge.
+
+1. The allocator is not yet optimal. Measured against the exact LP transportation optimum on real BPS data: the stable tier leaves 25.4% of equity-weighted welfare on the table, the greedy tier 11.1%. Concrete evidence: Sumenep's cabai_merah demand is only 26% filled even though reachable supply (2,662 t within 200 km) exceeds the need (1,418 t), greedy already committed that supply elsewhere first. So this is an optimality problem, not a scarcity problem. Plan: replace with a capacitated min-cost-flow / entropic-OT solver (milliseconds at province scale, provably optimal); greedy stays as v1. Root cause: `matching_engine/allocation.py:307`. Benchmark: `benchmarks/greedy_vs_optimal.py`.
+2. Unify the anomaly detectors. The user-facing anomaly panel already uses robust S-H-ESD (`analysis/price_anomaly.py`). But the internal D3 pre-filter gate (`matching_engine/engine.py:62`) still uses a non-robust 3σ z-score, on 70,953 real PIHPS observations it recalls only 14.4% of validated anomalies, and a D3 flag excludes a node from matching entirely. Plan: point D3 at the same S-H-ESD output (requires changing the `historical_prices` contract). Benchmark: `benchmarks/anomaly_detector_gap.py`.
+
+## Scaling Up
+
+National-scale growth is gated by the pace of public per-district data opening up, not technical readiness. Our approach: prove value at province scale with real data first, then expand as data becomes available.
+
+---
+
+## Running (quick technical)
+
+```bash
+pip install -r requirements.txt
+python examples/run_demo_real.py   # matching demo on real BPS 2022 data
+pytest tests/                      # 520 pass, 1 skipped
+```
+
+Full engineering detail in [`README_v12.md`](README_v12.md).
+
+---
+
+## License
+
+MIT License — &copy; 2026 Hilmi. See [`LICENSE`](LICENSE).
+
+<p align="center"><em>Detect · Predict · Distribute — for Indonesian food security.</em></p>

README.md

@@ -0,0 +1,240 @@
+---
+title: AgriFlow API
+emoji: "🌾"
+colorFrom: green
+colorTo: yellow
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+Language / Bahasa: [English](./README.en.md) · **Bahasa Indonesia**
+
+<h1 align="center">AgriFlow</h1>
+
+<p align="center">
+  <strong>AI-Powered Food Security Intelligence Platform</strong><br/>
+  <em>Platform Matching Demand–Supply Pangan Antarwilayah</em>
+</p>
+
+<p align="center"><b>Deteksi · Prediksi · Distribusi</b></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/PIDI-DIGDAYA%20%C3%97%20Hackathon%202026-1B5E20?style=for-the-badge" alt="Hackathon"/>
+  <img src="https://img.shields.io/badge/Problem%20Statement-2%20Matching%20Demand–Supply-4CAF50?style=for-the-badge" alt="PS"/>
+  <img src="https://img.shields.io/badge/tests-520%20passing-brightgreen?style=for-the-badge" alt="Tests"/>
+</p>
+
+> **Roadmap proyek dibagi 3 Phase.** README teknis lengkap versi sebelumnya diarsipkan di [`README_v13.md`](README_v13.md) (snapshot terbaru), [`README_v12.md`](README_v12.md), dan [`README_v11.md`](README_v11.md).
+
+---
+
+<details>
+<summary><b>🖼️ Lihat Research Poster (klik untuk expand)</b></summary>
+
+<br/>
+
+<p align="center"><em>Poster riset tersedia di repo GitHub (tidak disertakan di Space: HF menolak file biner di luar Xet storage).</em></p>
+
+</details>
+
+---
+
+# 📍 Phase 1 — Tim & Tautan
+
+## Tim
+
+| Nama | Role | LinkedIn |
+|------|------|----------|
+| Chelsea | Data Analyst | [Chelsea](https://linkedin.com/in/chelseaayu) |
+| Hilmi | Data Architect | [Hilmi](https://linkedin.com/in/hilmi888/) |
+| Monika | UX Researcher | [Monika](https://linkedin.com/in/monika-hermiani) |
+| Irpan | Data Engineer | [Irpan](https://linkedin.com/in/irpanpilihanrambe) |
+
+## Tautan
+
+| Resource | Link |
+|----------|------|
+| Pitch Deck | [Canva](https://www.canva.com/design/DAHETj2ulzg/VIvgxVkQ6I9R24ucphy2mQ/view) |
+| Dashboard (Live Demo) | [agriflow-engine.vercel.app](https://agriflow-engine.vercel.app/) |
+| Proposal (v13) | [docs/AgriFlow_Proposal_v13.pdf](docs/AgriFlow_Proposal_v13.pdf) |
+
+---
+
+# 🚀 Phase 2 — Yang Sudah Kami Bangun (MVP)
+
+## Masalah
+
+Setiap tahun Indonesia kehilangan triliunan rupiah pangan — **40% terjadi di distribusi, bukan produksi**. Di satu kabupaten petani membuang cabai karena harga jatuh; di kabupaten sebelah harga melonjak karena langka. Pemda sering baru tahu krisis **2–3 minggu kemudian**.
+
+## Solusi
+
+**AgriFlow mencocokkan kabupaten surplus dengan kabupaten defisit** — seperti "Uber untuk pangan", tapi paham masa simpan (perishability), jarak jalan nyata, dan **keadilan untuk daerah tertinggal**. Tiga fungsi inti:
+
+- **Deteksi** — temukan anomali harga (lonjakan/anjlok) dari data harga harian.
+- **Prediksi** — perkirakan harga 30 hari ke depan.
+- **Distribusi** — cocokkan surplus → defisit secara cerdas & adil.
+
+## Arsitektur (High-Level)
+
+```
+   SUMBER DATA NYATA                AGRIFLOW ENGINE                  AKSES
+  (BPS · PIHPS · OSRM)        ┌──────────────────────────┐
+  produksi · konsumsi ──────▶ │ DETEKSI    anomali harga  │ ──┐
+  harga · populasi            │ PREDIKSI   forecast 30 hr │   ├──▶ Dashboard peta
+  per-kabupaten Jatim         │ DISTRIBUSI matching 4-lapis│  └──▶ WhatsApp bot
+                              └──────────────────────────┘
+```
+
+Tiga fungsi (Deteksi · Prediksi · Distribusi) berbagi satu sumber data nyata, lalu disajikan lewat Dashboard & WhatsApp.
+
+📄 **Detail metodologi tiap fitur — alasan pemilihan metode, cara kerja, evaluasi, validasi, dan sitasi paper: [Dokumen Arsitektur (PDF)](docs/AgriFlow_Architecture.pdf).**
+
+## Fitur yang sudah berjalan
+
+| Fungsi | Fitur | Status |
+|--------|-------|:------:|
+| **Distribusi** | Matching engine 4-lapis (hard constraints → multi-objective scoring → equity) berjalan di **data BPS asli per-kabupaten (2022)** | ✅ |
+| **Deteksi** | Deteksi anomali harga (deseasonalize + robust statistics) pada harga PIHPS harian **2021–2025** | ✅ |
+| **Prediksi** | Forecasting harga 30 hari dengan **TimesFM 2.0** (foundation model time-series) | ✅ |
+| **Aksesibilitas** | **Chatbot WhatsApp** (tanya harga & rekomendasi) + **Dashboard** peta interaktif | ✅ |
+| **Keamanan** | Situs bersifat *login-first*: membuka website menampilkan halaman login lebih dulu. Juri cukup klik **"Masuk sebagai Tamu"** untuk meninjau tanpa membuat akun. Akun Supabase (JWT terverifikasi server-side, Row Level Security di 12 tabel, reset password) siap untuk model berlangganan; data sensitif (langganan & pembayaran) tetap dijaga verifikasi JWT di sisi server. | ✅ |
+| **Data nyata** | **6 komoditas** real per-kab: beras premium & medium, cabai merah & rawit, bawang merah & putih + harga PIHPS 5 tahun | ✅ |
+
+> **Kualitas:** 520 tes otomatis lulus (521 terkumpul, 1 di-skip) — engine teruji, dapat direproduksi, dan jujur soal keterbatasannya (lihat [Pengujian & Skenario](#pengujian--skenario) dan Phase 3).
+
+### Cuplikan
+
+**Dashboard** — peta Jawa Timur dengan bubble surplus/defisit per kabupaten, daftar *top matches*, plus panel **Forecast & Anomali harga** (ketiga fungsi dalam satu layar):
+
+*(Tangkapan layar dashboard ada di repo GitHub.)*
+
+**WhatsApp Bot** — tanya harga, cari pembeli/pemasok, prediksi & anomali harga lewat chat. Mendukung **Bahasa Indonesia** dan **Bahasa Jawa** (inklusi petani daerah):
+
+*(Tangkapan layar percakapan WhatsApp dalam kedua bahasa ada di repo GitHub.)*
+
+## Pengujian & Skenario
+
+Karena output AgriFlow menggerakkan alokasi pangan antar-kabupaten yang menyentuh daerah IPM-rendah, klaim "adil" dan "robust" harus dapat diaudit ulang — bukan sekadar narasi. Suite uji mengunci angka food-balance sebagai *golden numbers* (reproducibility), menjaga parameter kebijakan dari pergeseran tak sengaja (regression-safety), dan menguji deteksi anomali secara adversarial.
+
+**521 tes terkumpul · 520 lulus · 1 di-skip · lintas-OS di CI.**
+(Skip = `test_timesfm_importorskip`: dilewati jika pustaka TimesFM tak terpasang di runner; jalur forecasting tetap diuji via fallback + kontrak API.)
+
+Server produksi memuat **data BPS asli secara default** (`DATA_BACKEND=csv`, bawaan). Fixture sintetis 19-komoditas lama tetap dipakai di 13 file test (`DATA_BACKEND=demo`) untuk menguji logika engine di lebih banyak variasi komoditas — tidak pernah disajikan ke pengguna.
+
+| Kategori | Jumlah | Cakupan |
+|---|---|---|
+| Unit per-layer (L0–L3) | 73 | Tier IPM, constraint jarak/perishability, skor, alokasi equity |
+| 24 skenario edge-case (A–F) | 27+ | Volume, spasial, temporal, disrupsi, politis, kualitas |
+| Validasi data nyata BPS/PIHPS | 57 | Food-balance beras + hortikultura 2022, pipeline reproducible |
+| Deteksi anomali harga | 49 | S-H-ESD sadar-musiman pada residual deseasonalized |
+| Forecast & API | 40 | Endpoint forecast/anomali + fallback |
+| Baseline & equity | 39 | greedy/uniform/proporsional vs AgriFlow + skenario langka pasokan |
+| Ingest & integrasi | 73 | DB loader, ingest PIHPS, jarak OSRM, bot WhatsApp |
+| Autentikasi dashboard & kuota WhatsApp | 117 | Login Supabase, verifikasi JWT server-side, RLS 12 tabel, reset password, kuota gratis WhatsApp (nonaktif default) |
+
+**24 skenario edge-case** memetakan kejadian nyata Jawa Timur, contohnya: Ramadan spike (C1), erupsi Semeru di Lumajang → unreachable (D4), banjir multi-kabupaten sentra padi (D5), kenaikan BBM → biaya logistik naik (E5), dan prioritas reserve kontrak Bulog (E3).
+
+**Hasil kunci:**
+- **Equity terbukti saat pasokan langka, biaya efisiensi nol.** *Ini uji-tekan hipotetis, bukan hasil data BPS asli:* Jawa Timur pada data 2022 justru sangat surplus (rasio 6,6×), sehingga nilai equity tidak akan tampak. Untuk menunjukkan cara kerja mekanismenya kami membangun skenario langka buatan (fixture `surplus_deficit_constrained.csv`, surplus 3962t vs defisit 5249t). Di skenario itu greedy murni menelantarkan Madura — Sampang **0%**, Bangkalan **20%**; AgriFlow mengangkat keduanya ke **100%** dengan *coverage agregat identik* (0.6649) dan Gini turun (0.3017 → 0.2905). Kami tidak mengklaim keunggulan equity saat pasokan melimpah, dan tidak mengklaim skenario ini berasal dari data nyata.
+- **Anomali sadar-musiman.** Penurunan harga ~60% ter-flag, tapi pola musiman murni (siklus jelang Lebaran) **tidak** memicu false positive; anomali genuine di atas pola musiman tetap terdeteksi.
+- **Data mengungkap defisit struktural, bukan bug.** Bawang putih menghasilkan **0 match** di seluruh 38 kabupaten pada data BPS 2022 — Jawa Timur defisit bawang putih di semua kabupaten, konsisten dengan Indonesia sebagai net-importir bawang putih. Engine bekerja benar; datanya yang bicara.
+
+📄 Detail lengkap (kenapa, daftar 24 skenario, sitasi paper): [Dokumen Arsitektur](docs/AgriFlow_Architecture.pdf) §Pengujian & Validasi.
+
+## Kenapa tech stack kami RINGKAS (bukan sebanyak proposal awal)?
+
+Proposal awal mencantumkan stack besar (Qdrant, LangChain, Redis, n8n, multi-cloud, dll). Setelah benar-benar membangun, kami **sengaja memangkasnya** — *honest engineering* untuk skala saat ini (38 kabupaten Jawa Timur):
+
+| Rencana awal | Yang kami pakai | Alasan |
+|---|---|---|
+| Qdrant (vector DB terpisah) | **Supabase pgvector** | Korpus kecil — tak perlu service vektor sendiri |
+| LangChain | **Gemini API langsung** | RAG sesederhana ini tak butuh framework berat |
+| Redis cache | **In-process cache** | Beban belum menuntut; engine deterministik |
+| 5 platform hosting | **2 (HF Spaces + Vercel)** | Lebih sedikit titik gagal, lebih murah |
+
+**Prinsip kami: pakai yang cukup, bukan yang ramai.** Komponen besar baru bernilai saat skala membenarkannya — dan itulah **Phase 3**.
+
+## 🎙️ Validasi Lapangan — Wawancara Petani
+
+Kami mewawancarai **4 petani lintas komoditas & skala usaha** — dari petani mapan dengan jaringan pasar sampai petani kecil yang terkurung tengkulak — untuk memvalidasi kebutuhan nyata dan menemukan gap AgriFlow. Tiap baris menyertakan **rekaman audio sebagai bukti**.
+
+| Komoditas | Profil Narasumber | Pendapat Singkat | Rekaman & Transkrip |
+|---|---|---|---|
+| **Bawang Merah** | Denisa Septalian — petani penerus, Nganjuk (Ds. Ngudikan, Kec. Wilangan), 5 thn, lahan ±70 ru | **Setuju bersyarat.** Info harga saja "kurang efektif" karena 100% bergantung tengkulak & tak punya akses luar daerah — antusias bila AgriFlow membuka **akses pembeli luar kota**. | [🎧 Audio](https://drive.google.com/drive/folders/1kdF9KPqycrdN9GewRz6YKFUKWfzCaRVh) · [📄 Transkrip](interview/transcript-bawang-merah.md) |
+| **Padi** | Petani 15 thn, lahan ±1 ha; jual gabah ~Rp5.800/kg ke tengkulak yang datang ke sawah | Info harga lintas daerah **membantu** sebagai gambaran; tertarik pembeli luar kota asal prosesnya aman; ragu "ribet" di awal & soal keamanan transaksi. | [🎧 Audio](https://drive.google.com/drive/folders/1-fpMk8UGg41wk1-RZufTyRBNNJwM7he7) · [📄 Transkrip](interview/transcript-padi.md) |
+| **Cabai** | Petani baru (8 bln bertani, tanaman 50 HST), Solo/Karanganyar; sebelumnya jagung | **Sangat tertarik** harga real-time antar daerah untuk hitung kelayakan kirim; info FB/WA kini meleset Rp5.000–15.000/kg & hanya level provinsi. Menekankan UI sederhana untuk petani lansia. | [🎧 Audio](https://drive.google.com/drive/folders/1lStLTY4L_9NW-UXAWrfTXwNc0CuiUQT-) · [📄 Transkrip](interview/transcript-cabai.md) |
+| **Kentang** | Labib — Dieng, Banjarnegara, ±6 ha, 2 thn; jual ke Pasar Induk Kramat Jati | Info antar daerah berguna sebagai **pembanding & referensi keputusan**, tetap utamakan pedagang langganan. Kunci keberhasilan: **akurasi data + sumber jelas + update real-time**. | [🎧 Audio](https://drive.google.com/drive/folders/1mMVWLv6uQQzlD_KNrkI5eSARXHTlDK9K) · [📄 Transkrip](interview/transcript-kentang.md) |
+
+### Analisis & Kesimpulan — Nilai Plus AgriFlow yang Tervalidasi
+
+- **Masalah inti tervalidasi lintas komoditas.** Keempat petani menyebut keluhan yang sama: harga tidak stabil, panen raya serentak → harga anjlok, dan **butaan informasi harga antar daerah** — persis yang dijawab fungsi **Deteksi + Prediksi**.
+- **WhatsApp sebagai kanal — tervalidasi 4/4.** Semua memilih WhatsApp (bisa dibaca ulang, sudah dipakai semua petani) di atas SMS/aplikasi baru → memperkuat keputusan **WhatsApp bot**.
+- **Matching surplus→defisit menjawab keluhan paling tajam.** "Tidak ada akses keluar daerah" (bawang merah, padi) adalah problem yang langsung diselesaikan **matching engine 4-lapis**; begitu ditawari pembeli luar kota berharga lebih baik, **keempatnya tertarik**.
+- **Prediksi harga punya nilai konkret.** Semua pernah "kesusu" / salah memperkirakan harga (bawang merah sempat jual Rp10.000, dua hari kemudian Rp20.000) → **forecast 30 hari** menjawab kebutuhan ini.
+- **Kesediaan membayar ada** — bersyarat manfaat ekonomi terbukti & data akurat. Tak satu pun menolak model berbayar.
+
+> Temuan **gap fitur** dari wawancara (akses transaksi, granularitas harga, transparansi & keamanan) kami petakan secara jujur ke **Phase 3** di bawah.
+
+---
+
+# 🌐 Phase 3 — Rencana Lanjutan & Scaling
+
+Phase 3 memuat dua hal yang kami pisahkan secara jujur: fitur yang sengaja ditunda karena belum dibutuhkan pada skala sekarang, dan batas yang sudah kami ukur pada engine yang berjalan lalu kami jadwalkan perbaikannya.
+
+## Yang ditunda (menunggu data atau beban nyata)
+
+| Rencana | Untuk apa | Pemicu |
+|---|---|---|
+| Skala nasional 514 kab | Dari 38 kab Jatim ke seluruh Indonesia | spatial partitioning + precompute jarak |
+| Exogenous forecasting (indeks ENSO, kalender Ramadan) | Akurasi naik saat guncangan iklim & hari raya | data eksogen tersedia |
+| Daging ayam & telur (data real) | Melengkapi 6 komoditas inti | produksi broiler & telur-ras per-kab dirilis |
+| Harga granular per kota/pasar | Selisih riil bisa Rp5.000 sampai 15.000/kg (wawancara cabai) | feed harga pasar terbuka |
+| Fasilitasi transaksi antar-daerah | Info harga saja "kurang efektif" tanpa saluran jual-beli (wawancara bawang & padi) | kemitraan penyaluran |
+| Transparansi sumber & keamanan transaksi | Syarat kepercayaan pengguna (wawancara) | tahap kemitraan resmi |
+| Sahabat-AI (Jawa/Madura) + IVR telepon | Inklusi petani lansia & feature-phone | tahap penskalaan kanal |
+| Qdrant / Redis / n8n | Vector scale, caching, orkestrasi | saat beban nyata muncul |
+
+## Batas cakupan hari ini (gerbangnya ketersediaan data, bukan arsitektur)
+
+Engine sudah siap memproses data apa pun; yang membatasi adalah ketersediaan data publik per-kabupaten. Begitu sumbernya terbuka, pipeline yang sama langsung memprosesnya tanpa ubah arsitektur.
+
+| Cakupan sekarang | Gerbangnya |
+|---|---|
+| 6 komoditas inti | menunggu produksi per-kab komoditas lain dirilis BPS |
+| Tahun acuan 2022 | tahun terlengkap di semua sumber per-kab; tahun baru tinggal di-ingest |
+| Daging ayam & telur belum | 13 komoditas lain masih placeholder sintetis, tidak disajikan ke pengguna (`DATA_BACKEND=csv`) |
+| Konsumsi cabai/bawang via angka nasional | konsumsi beras sudah per-kab & dipakai nyata; sisanya menunggu publikasi |
+| Harga Tier-2 (kab non-IHK) | Panel Harga Bapanas dalam pemeliharaan; saat feed pulih, 30+ kab langsung tercakup |
+
+## Utang teknis yang sudah kami ukur (perbaikan terjadwal)
+
+Dua batas ini kami ukur sendiri terhadap performa maksimal engine, dengan benchmark yang di-commit dan dapat direproduksi juri.
+
+1. Allocator belum optimal. Diuji terhadap optimum LP transportation eksak pada data BPS asli: tier stable meninggalkan 25,4% welfare berbobot-ekuitas, tier greedy 11,1%. Bukti nyata: permintaan cabai_merah Sumenep terisi 26% padahal pasokan terjangkau (2.662 ton, radius 200 km) melebihi kebutuhan (1.418 ton), greedy mengalokasikannya lebih dulu ke tempat lain. Jadi ini soal optimalitas, bukan kelangkaan. Rencana: ganti ke solver capacitated min-cost-flow / entropic-OT (milidetik pada skala provinsi, provably optimal); greedy tetap sebagai v1. Akar: `matching_engine/allocation.py:307`. Benchmark: `benchmarks/greedy_vs_optimal.py`.
+2. Satukan detektor anomali. Panel anomali pengguna sudah pakai S-H-ESD robust (`analysis/price_anomaly.py`). Namun gerbang pre-filter D3 internal (`matching_engine/engine.py:62`) masih z-score 3σ non-robust, pada 70.953 observasi PIHPS asli hanya me-recall 14,4% anomali tervalidasi, dan flag D3 mengeluarkan node dari matching sepenuhnya. Rencana: arahkan D3 ke output S-H-ESD yang sama (perlu ubah kontrak `historical_prices`). Benchmark: `benchmarks/anomaly_detector_gap.py`.
+
+## Scaling up
+
+Peningkatan skala nasional dibatasi laju keterbukaan data publik per-kabupaten, bukan kesiapan teknis. Pendekatan kami: buktikan nilai dulu di skala provinsi dengan data nyata, lalu perluas seiring data tersedia.
+
+---
+
+## Menjalankan (teknis singkat)
+
+```bash
+pip install -r requirements.txt
+python examples/run_demo_real.py   # demo matching pada data BPS asli 2022
+pytest tests/                      # 520 lulus, 1 di-skip
+```
+
+Detail engineering lengkap ada di [`README_v12.md`](README_v12.md).
+
+---
+
+## Lisensi
+
+MIT License — &copy; 2026 Hilmi. Lihat [`LICENSE`](LICENSE).
+
+<p align="center"><em>Deteksi · Prediksi · Distribusi — untuk ketahanan pangan Indonesia.</em></p>

README_v10.md

@@ -0,0 +1,639 @@
+# AgriFlow Matching Engine
+
+> **Sub-national pangan matching engine pertama di Indonesia.**
+> Algoritma 4-lapis hybrid yang menghubungkan kabupaten surplus dengan defisit menggunakan stable matching, multi-objective scoring 5 dimensi, dan equity multiplier untuk kabupaten tertinggal — semua untuk komoditas pangan tingkat kabupaten.
+
+[![Tests](https://img.shields.io/badge/tests-106%2F106%20passing-brightgreen)]()
+[![Latency](https://img.shields.io/badge/p99%20latency-1.4ms%20%E2%86%92%2055.5ms-blue)]()
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()
+[![Status](https://img.shields.io/badge/status-provincial--ready-success)]()
+
+Submisi **PIDI DIGDAYA × Hackathon 2026** — Bank Indonesia.
+Problem Statement #2: Platform Matching Demand-Supply Antarwilayah.
+
+---
+
+## Daftar Isi
+
+- [Apa Ini?](#apa-ini)
+- [Quick Start (5 menit)](#quick-start-5-menit)
+- [Arsitektur 4-Lapis](#arsitektur-4-lapis)
+- [Equity Multiplier (Kalibrasi BPS 2024)](#equity-multiplier-kalibrasi-bps-2024)
+- [19 Skenario Edge Case](#19-skenario-edge-case)
+- [API Usage](#api-usage)
+- [Performance & Validation](#performance--validation)
+- [Data Sources](#data-sources)
+- [Project Structure](#project-structure)
+- [Development Guide](#development-guide)
+- [Status & Roadmap](#status--roadmap)
+- [Documentation](#documentation)
+- [License & Credits](#license--credits)
+
+---
+
+## Apa Ini?
+
+**Bayangkan Uber, tapi untuk cabai dan bawang merah.**
+
+Setiap hari, Indonesia kehilangan Rp 213-551 triliun pangan karena food loss & waste — 40% di distribusi, bukan produksi. Petani di Sampang membuang cabai karena harga jatuh, sementara pasar Surabaya melonjak 200% karena kelangkaan. Pemda baru tahu krisis 2-3 minggu kemudian.
+
+AgriFlow Matching Engine memecahkan ini dengan 6 dimensi yang Uber tidak punya:
+
+| Dimensi | Penjelasan |
+|---|---|
+| **Perishability** | Cabai busuk dalam 5 hari, beras tahan 180 hari — engine hitung shelf life |
+| **Equity** | Kabupaten tertinggal IPM rendah (Sampang 66.72) dapat boost +30% |
+| **Climate** | Banjir di rute = re-route otomatis |
+| **Volume** | 1 surplus bisa di-split ke banyak deficit |
+| **Stable Matching** | Guarantee fairness via Gale-Shapley (Nobel Prize Economics 2012) |
+| **Two-tier Confidence** | Data harian PIHPS (Tier 1) pakai algoritma ketat; data mingguan Bapanas (Tier 2) pakai algoritma fleksibel |
+
+**Status:** Production-ready untuk skala provinsial (38 kab Jatim) — 106/106 tests pass dalam 0.16s, latency p99 1.4ms (sample) - 55.5ms (stress 361×361).
+
+---
+
+## Quick Start (5 menit)
+
+### Prasyarat
+
+- Python 3.10+
+- pip
+- ~50MB disk space
+
+### Install
+
+```bash
+git clone https://github.com/masterA88/agriflow_engine.git
+cd agriflow_engine
+python -m venv venv
+# Windows:
+venv\Scripts\activate
+# Linux/Mac:
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### Verifikasi (semua harus sukses)
+
+```bash
+# 1. Generate sample data — 38 kab × 19 komoditas Jatim
+python sample_data/generate_sample_data.py
+# Expected: 5 CSV generated (kabupaten_jatim.csv, komoditas_constraints.csv,
+#           surplus_deficit.csv, weather_forecast.csv, historical_price_stats.csv)
+
+# 2. Run all tests (106 tests)
+pytest tests/ -v
+# Expected: 106 passed in <1s
+
+# 3. Run end-to-end demo
+python examples/run_demo.py
+# Expected: ~32 matches, gross arbitrage ~Rp 16 miliar, latency ~1.5ms
+
+# 4. Run latency benchmark
+python benchmarks/latency.py
+# Expected: highest p99 < 60ms (margin >88% vs 500ms target)
+```
+
+Kalau langkah 2 atau 3 gagal, lihat [Troubleshooting](#troubleshooting) di bawah.
+
+---
+
+## Arsitektur 4-Lapis
+
+```
+Input: surplus_nodes[], deficit_nodes[], LogisticsContext, weather, historical_prices
+
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 0 — Tier Classification (constraints.determine_tier)      │
+  │   Klasifikasi setiap kab: Tier 1 HIGH (8 kota IHK PIHPS) atau   │
+  │   Tier 2 MEDIUM (30 kab non-IHK Bapanas).                       │
+  │   Latency: <1ms (set lookup).                                   │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 1 — Hard Constraints (constraints.generate_candidates)    │
+  │   9 rules filter: komoditas match, distance≤max, age≤shelf,     │
+  │   volume≥min, no self-match, emergency mode, pemda override,    │
+  │   Bulog split, BBM-aware distance shrink.                       │
+  │   Output: candidate pairs (top-K per surplus by jarak).         │
+  │   Latency: <50ms untuk 38×19 (~25k pasang potensial).           │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 2 — Multi-Objective Scoring (scoring.compute_score)       │
+  │   5-dimensi weighted: Distance 22% / Volume 22% / Price 22% /   │
+  │   Perishability 18% / Climate 16%.                              │
+  │   3 weight schemes: DEFAULT, RAMADAN, IMPORT_POLICY.            │
+  │   Output: base_score 0-100 per pair.                            │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 3 — Equity-Weighted Allocation (allocation.allocate)      │
+  │   Final = base × equity_multiplier(IPM_deficit).                │
+  │   Tier 1↔Tier 1 → Modified Gale-Shapley (Nobel 2012).           │
+  │   Cross-tier / Tier 2 → Greedy with equity priority.            │
+  │   Output: MatchResult[] dengan confidence label.                │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ POST-PROCESSING (engine.run_matching)                           │
+  │   Tag flags (RAMADAN_SPIKE, EQUITY_BOOST_30, MADURA_CLUSTER,    │
+  │   STALE_DATA_24H, HUMANITARIAN_PRIORITY, VOLUME_MISMATCH).      │
+  │   Identifikasi unmatched + external_opportunities (ekspor).     │
+  └─────────────────────────────────────────────────────────────────┘
+
+Output: MatchingReport(matches, unmatched_*, warnings, run_metadata)
+```
+
+**Why 4-layer?** Setiap layer bisa dioptimasi independent, testable secara isolated, dan early-exit di Layer 1 menghemat compute Layer 2/3 yang lebih mahal.
+
+---
+
+## Equity Multiplier (Kalibrasi BPS 2024)
+
+Threshold dikalibrasi sesuai distribusi IPM 2024 BPS Jatim sehingga klaim "+30% boost untuk kab tertinggal" konkret applicable:
+
+| IPM Range | Multiplier | Boost | Kab/Kota Jatim |
+|---|---|---|---|
+| `IPM < 68` | **1.30** | **+30%** | Sampang (66.72), Bangkalan (67.70) |
+| `68 ≤ IPM < 72` | 1.15 | +15% | Sumenep, Probolinggo (kab), Bondowoso, Lumajang, Pamekasan, Pacitan, Pasuruan (kab), Situbondo, Jember, Madiun (kab) |
+| `72 ≤ IPM < 78` | 1.05 | +5% | Bojonegoro, Banyuwangi, Tulungagung, Malang (kab), Magetan, Gresik, Mojokerto (kab), Lamongan, Tuban, Ngawi, Kediri (kab), dll |
+| `IPM ≥ 78` | 1.00 | (no boost) | Sidoarjo, Kota Batu, Kota Surabaya, Kota Malang, Kota Kediri, Kota Madiun, dll |
+
+**Mengapa kalibrasi:** Threshold v9 lama (`<65 → 1.30`) tidak pernah ter-trigger karena IPM terendah Jatim 2024 = Sampang 66.72. v10 menggeser threshold sehingga klaim "+30% boost" demonstrably valid.
+
+**Update IPM tahunan:** Saat BPS publish IPM baru (biasanya BRS Desember), edit di [`sample_data/generate_sample_data.py:KABUPATEN_DATA`](sample_data/generate_sample_data.py) sebagai source of truth, lalu mirror ke [`data_sources/bps.py:IPM_2024_JATIM`](data_sources/bps.py).
+
+---
+
+## 19 Skenario Edge Case
+
+5 kategori, 19 skenario, semua tervalidasi pytest. Detail lengkap di [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) dan `AgriFlow_v10.docx` Section 5.5.5.
+
+### Kategori A — Volume (4 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| A1 | Surplus 1-to-many (1 surplus split ke beberapa deficit) | `TestA1_OneToMany` |
+| A2 | Many-to-1 (multiple surplus untuk 1 deficit besar) | `TestA2_ManyToOne` |
+| A3 | Volume mismatch drastis (<20% ratio → flag warning) | `TestA3_VolumeMismatchDrastis` |
+| A4 | Zero demand (suggest external opportunity) | `TestA4_ZeroDemand` |
+
+### Kategori B — Spasial (3 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| B1 | Cross-tier match (Tier 1 ↔ Tier 2) | `TestB1_CrossTier` |
+| B2 | Long distance (jarak > max_distance_km → REJECT) | `TestB2_LongDistance` |
+| B3 | Cluster Madura (4 kab semua surplus → ekspor) | `TestB3_ClusterMadura` |
+
+### Kategori C — Temporal (3 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| C1 | Ramadan/Idul Fitri spike (H-21 to H-1, RAMADAN_WEIGHTS) | `TestC1_RamadanSpike` |
+| C2 | Pasca panen raya (oversupply, multiple match) | `TestC2_PostHarvest` |
+| C3 | Stale data >24h (confidence drop bertingkat HIGH→MEDIUM→LOW) | `TestC3_StaleData` |
+
+### Kategori D — Disrupsi (5 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| D1 | Banjir rute (BMKG hujan >50mm → climate_score 0.3) | `TestD1_BanjirRute` |
+| D2 | Komoditas hampir rusak (harvest age + transit > shelf) | `TestD2_KomoditasRusak` |
+| D3 | Harga anomali (>3σ dari rolling median → exclude) | `TestD3_HargaAnomali` |
+| D4 | Erupsi gunung (PVMBG MAGMA → UNREACHABLE) | `TestD4_ErupsiGunung` |
+| D5 | Banjir multi-kab (BNPB DIBI → emergency mode) | `TestD5_BanjirMultiKab` |
+
+### Kategori E — Politis & Kebijakan (5 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| E1 | Equity tie-break (IPM lebih rendah menang otomatis) | `TestE1_EquityTieBreak` |
+| E2 | Pemda override (`do_not_export_<komoditas>` flag) | `TestE2_PemdaOverride` |
+| E3 | Bulog priority (60% reserve, sisa 40% private) | `TestE3_BulogPriority` |
+| E4 | Import policy aktif (IMPORT_POLICY_WEIGHTS, price weight ↓) | `TestE4_ImportPolicy` |
+| E5 | BBM naik (max_distance shrink, logistics cost ↑) | `TestE5_BBMNaik` |
+
+---
+
+## API Usage
+
+### Programmatic API
+
+```python
+from matching_engine import (
+    run_matching, SupplyNode, DemandNode,
+    Kabupaten, Tier, Commodity, LogisticsContext,
+)
+
+# Setup kabupaten (real koordinat & IPM 2024 BPS)
+kediri = Kabupaten(
+    id="3506", nama="Kediri",
+    latitude=-7.796, longitude=112.170,
+    ipm=74.50, tier=Tier.MEDIUM,
+)
+surabaya = Kabupaten(
+    id="3578", nama="Kota Surabaya",
+    latitude=-7.2575, longitude=112.7521,
+    ipm=84.69, tier=Tier.HIGH,
+)
+
+# Setup komoditas (constraint per komoditas)
+cabai = Commodity(
+    code="cabai_merah", nama="Cabai Merah Besar",
+    max_distance_km=200, min_viable_tons=1.0,
+    max_fresh_age_days=5,
+)
+
+# Run matching
+report = run_matching(
+    surplus_nodes=[
+        SupplyNode(kediri, cabai, volume_tons=80, price_per_kg=30000),
+    ],
+    deficit_nodes=[
+        DemandNode(surabaya, cabai, volume_tons=80, price_per_kg=60000),
+    ],
+    logistics=LogisticsContext(),
+)
+
+# Inspect hasil
+for m in report.matches:
+    print(f"{m.surplus.kabupaten.nama} → {m.deficit.kabupaten.nama}")
+    print(f"  Volume: {m.matched_volume_tons}t @ {m.distance_km:.0f}km")
+    print(f"  Score: {m.final_score:.1f} (base {m.base_score:.1f} × {m.equity_multiplier})")
+    print(f"  Confidence: {m.confidence.value}, Flags: {m.flags}")
+
+# Output:
+# Kediri → Kota Surabaya
+#   Volume: 80.0t @ 65km
+#   Score: 89.5 (base 89.5 × 1.0)
+#   Confidence: MEDIUM, Flags: []
+
+print(f"\nLatency: {report.run_metadata['latency_ms']}ms")
+print(f"Candidate pairs evaluated: {report.run_metadata['candidate_pairs_evaluated']}")
+print(f"Warnings: {len(report.warnings)}")
+```
+
+### Advanced — Skenario Override
+
+```python
+from matching_engine.constraints import set_bulog_procurement
+from datetime import datetime
+
+# Skenario E3: Bulog procurement aktif untuk Madiun
+set_bulog_procurement({"3519"})
+
+# Skenario E4: Import policy aktif (bobot price diturunkan)
+report = run_matching(
+    surplus_nodes=[...],
+    deficit_nodes=[...],
+    import_policy_active=True,  # IMPORT_POLICY_WEIGHTS
+)
+
+# Skenario C1: Force Ramadan mode untuk testing
+report = run_matching(
+    surplus_nodes=[...],
+    deficit_nodes=[...],
+    reference_date=datetime(2026, 3, 6),  # H-14 Idul Fitri 2026
+)
+
+# Skenario E5: BBM naik 20%
+from matching_engine.models import LogisticsContext
+report = run_matching(
+    surplus_nodes=[...],
+    deficit_nodes=[...],
+    logistics=LogisticsContext(
+        bbm_price_idr_per_liter=12000,
+        bbm_price_baseline=10000,
+    ),
+)
+```
+
+### Advanced — Force Algorithm Strategy
+
+```python
+# Force stable matching (Tier 1 algorithm)
+report = run_matching(..., force_strategy="stable")
+
+# Force greedy (Tier 2 algorithm) untuk testing
+report = run_matching(..., force_strategy="greedy")
+
+# Auto-detect (default): Tier 1↔Tier 1 pairs → stable, else → greedy
+report = run_matching(...)
+```
+
+---
+
+## Performance & Validation
+
+### Test Suite
+
+```bash
+$ pytest tests/ --tb=short
+============================= test session starts =============================
+collected 106 items
+
+tests/test_layer0_tier.py ................                           [ 15%]
+tests/test_layer1_constraints.py ...................                 [ 33%]
+tests/test_layer2_scoring.py .......................                 [ 54%]
+tests/test_layer3_allocation.py ..............                       [ 67%]
+tests/test_scenarios_disruption.py .........                         [ 76%]
+tests/test_scenarios_political.py ........                           [ 83%]
+tests/test_scenarios_spatial.py ......                               [ 89%]
+tests/test_scenarios_temporal.py .......                             [ 96%]
+tests/test_scenarios_volume.py ....                                  [100%]
+
+============================= 106 passed in 0.16s =============================
+```
+
+### Latency Benchmark
+
+```bash
+$ python benchmarks/latency.py
+```
+
+| Configuration | N (s × d) | p50 | p95 | p99 | Max |
+|---|---|---|---|---|---|
+| Sample data CSV (realistic) | 40 × 33 | 0.99 ms | 1.26 ms | 1.38 ms | 1.42 ms |
+| Synthetic full Jatim (38×19) | 361 × 361 | 48.37 ms | 53.67 ms | 55.53 ms | 58.43 ms |
+| Stress 100×100 (national scale) | 100 × 100 | 12.62 ms | 14.82 ms | 15.51 ms | 15.65 ms |
+| Stress 200×200 | 200 × 200 | 25.47 ms | 26.92 ms | 27.54 ms | 27.76 ms |
+
+**Verdict:** PASS — semua p99 < 500ms target. Highest p99 = 55.53ms (margin 88.9%).
+
+### National Scale (Indonesia 514 kab)
+
+⚠ **HONEST DISCLOSURE:** Engine v10 saat ini BELUM siap untuk produksi nasional 514 kab. Lihat [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) Section 3.2 untuk detail. Optimization roadmap (spatial indexing, per-provinsi batching, parallel) sudah ter-quantify untuk Y2-Y3.
+
+```bash
+$ python benchmarks/national_scale.py
+```
+
+| Scale | Workload | p99 | vs target |
+|---|---|---|---|
+| Provinsi Jatim baseline | 333×389 | **14.2ms** | ✅ 35× under |
+| Multi-provinsi (100 kab) | 948×952 | **94.5ms** | ✅ 5× under |
+| Setengah Indonesia (250 kab) | 2326×2424 | **541.8ms** | ⚠ 1.08× over |
+| **Full Indonesia (514 kab)** | **4859×4907** | **2223.3ms** | ❌ **4.4× over** |
+
+---
+
+## Data Sources
+
+8 connector dengan dual-mode (mock CSV + live API), graceful fallback:
+
+| Connector | Sumber | Frekuensi | Auth | Tier |
+|---|---|---|---|---|
+| [`pihps_bi.py`](data_sources/pihps_bi.py) | Bank Indonesia PIHPS | Harian (cut-off 13:00 WIB) | Tidak ada (scrape publik) | Tier 1 |
+| [`bapanas.py`](data_sources/bapanas.py) | Panel Harga Bapanas | Mingguan (Senin) | Tidak ada | Tier 2 |
+| [`bps.py`](data_sources/bps.py) | BPS WebAPI (IPM, produksi) | Tahunan (BRS Desember) | API key gratis | Both |
+| [`bmkg.py`](data_sources/bmkg.py) | BMKG / Open-Meteo (cuaca) | 3-6 jam refresh | Tidak ada (Open-Meteo) | Both |
+| [`pvmbg.py`](data_sources/pvmbg.py) | PVMBG MAGMA (gunung api) | Realtime saat status berubah | Tidak ada | Both |
+| [`bnpb.py`](data_sources/bnpb.py) | BNPB DIBI (bencana) | Realtime | Tidak ada | Both |
+| [`google_maps.py`](data_sources/google_maps.py) | Google Routes / OSRM fallback | Realtime per request | Google API key (paid) / OSRM gratis | Both |
+| [`hijri_calendar.py`](data_sources/hijri_calendar.py) | Aladhan API + hardcoded | Statis | Tidak ada | Both |
+
+### Fail-safe Strategy
+
+- Live API gagal → fallback ke mock CSV / hardcoded data
+- Weather data tidak tersedia → climate_score = 0.7 (neutral)
+- BPS API gagal → fallback ke `IPM_2024_JATIM` hardcoded
+- BMKG butuh adm4 mapping yang tidak ada → auto-fallback ke Open-Meteo
+- OSRM down → haversine geodesic + asumsi 60 km/h
+
+---
+
+## Project Structure
+
+```
+agriflow_engine/
+├── matching_engine/         # Core engine (5 modules, ~1000 lines)
+│   ├── __init__.py          # Public API
+│   ├── models.py            # Dataclasses (Kabupaten, Commodity, MatchResult, ...)
+│   ├── constraints.py       # Layer 0 + Layer 1 (9 hard constraints)
+│   ├── scoring.py           # Layer 2 (5-dim multi-objective scoring)
+│   ├── allocation.py        # Layer 3 (Gale-Shapley + Greedy + Equity)
+│   └── engine.py            # Main orchestrator + 19 skenario handlers
+├── data_sources/            # 8 connector dual-mode (mock + live)
+│   ├── pihps_bi.py          # Tier 1 PIHPS BI
+│   ├── bapanas.py           # Tier 2 Bapanas
+│   ├── bps.py               # IPM 2024 + produksi BPS
+│   ├── bmkg.py              # Cuaca BMKG/Open-Meteo
+│   ├── pvmbg.py             # Erupsi gunung PVMBG MAGMA
+│   ├── bnpb.py              # Bencana BNPB DIBI
+│   ├── google_maps.py       # Routing Google/OSRM
+│   └── hijri_calendar.py    # Ramadan/Idul Fitri Aladhan
+├── sample_data/             # CSV 38 kab × 19 komoditas Jatim
+│   ├── generate_sample_data.py  # Source of truth — regenerate CSV
+│   ├── loader.py                # CSV → engine objects
+│   ├── kabupaten_jatim.csv      # 38 kab + IPM 2024 + koordinat
+│   ├── komoditas_constraints.csv  # 19 komoditas + spec
+│   ├── surplus_deficit.csv      # 73 row sample workload
+│   ├── weather_forecast.csv     # 10 route forecast
+│   └── historical_price_stats.csv  # 19 commodity rolling stats
+├── tests/                   # 106 pytest test
+│   ├── conftest.py          # Fixtures (17 kab Jatim + factory)
+│   ├── test_layer0_tier.py             # 16 test (tier classification)
+│   ├── test_layer1_constraints.py      # 19 test (haversine + viability + Bulog)
+│   ├── test_layer2_scoring.py          # 23 test (5-dim scoring + weight schemes)
+│   ├── test_layer3_allocation.py       # 14 test (equity + stable + greedy)
+│   ├── test_scenarios_volume.py        # 4 test (A1-A4)
+│   ├── test_scenarios_spatial.py       # 6 test (B1-B3)
+│   ├── test_scenarios_temporal.py      # 7 test (C1-C3)
+│   ├── test_scenarios_disruption.py    # 9 test (D1-D5)
+│   └── test_scenarios_political.py     # 8 test (E1-E5)
+├── examples/
+│   └── run_demo.py          # End-to-end demo dengan output formatted
+├── benchmarks/
+│   ├── latency.py           # Multi-config provincial benchmark
+│   └── national_scale.py    # National scale stress test (514 kab)
+├── docs/
+│   ├── generate_v10_docx.py # Proposal v10 docx generator
+│   └── AUDIT_v10.md         # Audit lengkap (consistency + national scale analysis)
+├── README.md                # This file
+├── requirements.txt         # Python dependencies
+└── venv/                    # (gitignored) virtual env
+```
+
+---
+
+## Development Guide
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/masterA88/agriflow_engine.git
+cd agriflow_engine
+python -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -r requirements.txt
+pip install python-docx  # untuk regenerate proposal docx
+```
+
+### Workflow
+
+1. **Edit code** di `matching_engine/` atau `data_sources/`
+2. **Run test** sebelum commit: `pytest tests/ -v`
+3. **Update sample data** kalau ubah threshold/komoditas: `python sample_data/generate_sample_data.py`
+4. **Run demo** untuk smoke test: `python examples/run_demo.py`
+5. **Run benchmark** kalau perubahan di hot path: `python benchmarks/latency.py`
+6. **Regenerate proposal** kalau perubahan di logic: `python docs/generate_v10_docx.py`
+
+### Add New Skenario
+
+1. Tambah test class di file yang sesuai (mis. `tests/test_scenarios_volume.py`)
+2. Tambah behavior di `matching_engine/engine.py` post-processing atau Layer yang relevan
+3. Update `AgriFlow_v10.docx` Section 5.5.5 (regenerate via `docs/generate_v10_docx.py`)
+4. Pastikan `pytest tests/ -v` masih PASS
+
+### Add New Komoditas
+
+1. Tambah row di [`sample_data/generate_sample_data.py:KOMODITAS_DATA`](sample_data/generate_sample_data.py)
+2. Tambah row di [`matching_engine/constraints.py:COMMODITY_SPECS`](matching_engine/constraints.py) (samakan max_distance/min_viable/max_fresh_age)
+3. Run `python sample_data/generate_sample_data.py` untuk regenerate CSV
+4. Update assertion di test kalau komoditas count check
+
+### Update IPM Tahunan (saat BPS publish data baru)
+
+1. Edit [`sample_data/generate_sample_data.py:KABUPATEN_DATA`](sample_data/generate_sample_data.py) (source of truth)
+2. Mirror ke [`data_sources/bps.py:IPM_2024_JATIM`](data_sources/bps.py)
+3. Run `python sample_data/generate_sample_data.py` untuk regenerate CSV
+4. Re-evaluate equity threshold di [`matching_engine/allocation.py:38`](matching_engine/allocation.py) — apakah masih meaningful trigger untuk distribusi baru?
+5. Run `pytest tests/ -v` — beberapa test mungkin perlu update kalau IPM bergeser
+
+---
+
+## Status & Roadmap
+
+### Current Status: ✅ Provincial-Ready (Jatim)
+
+- [x] 4-layer architecture implemented
+- [x] 19 skenario edge case handled
+- [x] 106/106 tests passing
+- [x] Latency p99 1.4ms (sample) - 55.5ms (stress)
+- [x] Equity multiplier kalibrasi BPS 2024 — Sampang & Bangkalan menerima +30% boost
+- [x] 8 data source connector dual-mode
+- [x] Cross-platform demo (Windows/Linux/Mac)
+- [x] Reproducible documentation generator
+
+### Roadmap to National Scale (Y2-Y3)
+
+⚠ **Honest disclosure:** Engine v10 saat ini BELUM siap untuk produksi nasional 514 kab. p99 untuk full Indonesia = 2.2 detik (4.4× over 500ms target).
+
+**Optimization plan** (lihat [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) Section 6):
+
+| Quick Win | Effort | Impact |
+|---|---|---|
+| Fix double-haversine bug di `generate_candidates` | 1 jam | 30-40% speedup Layer 1 |
+| Add geohash precision-5 spatial pre-filter | 1-2 hari | 25-50× speedup Layer 1 |
+| Multiprocessing per komoditas | 2-3 hari | Up to 19× speedup |
+| Distance matrix precompute (Redis cache) | 4 jam | 5-10× speedup |
+| Per-provinsi batching | 1 minggu | 5-15× speedup |
+
+**Combined estimate:** ~100-200× speedup → bring p99 dari 2200ms ke ~10-20ms untuk 514 kab nasional.
+
+### Data/Coverage Expansion (Y2)
+
+- [ ] `TIER_1_KOTA_IHK`: 8 kota Jatim → ~90 kota IHK Indonesia
+- [ ] `IPM_2024_JATIM` → `IPM_2024_INDONESIA` (514 kab/kota)
+- [ ] Cluster definitions: Madura → 10-20 cluster nasional
+- [ ] `GUNUNG_KABUPATEN_MAP`: 6 gunung Jatim → 130+ gunung api Indonesia
+- [ ] Sample data: 38 kab → 514 kab synthetic + real
+
+### Architectural Expansion (Y2-Y3)
+
+- [ ] Inter-island logistics (transport mode: truck/ferry/cargo plane)
+- [ ] Equity threshold recalibration nasional (range IPM 50-85)
+- [ ] CI/CD pipeline (GitHub Actions: pytest + benchmark assertions)
+- [ ] FastAPI wrapper untuk REST API production
+- [ ] Hybrid stable+greedy untuk skenario campuran tier
+- [ ] LLM integration (Gemini + Sahabat-AI Bahasa Daerah)
+
+---
+
+## Documentation
+
+| Document | Lokasi | Deskripsi |
+|---|---|---|
+| **Proposal v10** | Generate via `python docs/generate_v10_docx.py` | Proposal lengkap 14 section: business + technical (docx tidak ditracking di repo — internal team artifact) |
+| **Audit v10** | [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) | Consistency check + national scale analysis |
+| **README** | This file | Quick reference + getting started |
+| **Generator script** | [`docs/generate_v10_docx.py`](docs/generate_v10_docx.py) | Regenerate proposal docx dari source |
+| **Code comments** | All `.py` files | Inline docstrings dengan reference ke proposal section |
+
+---
+
+## Troubleshooting
+
+### "ModuleNotFoundError: No module named 'matching_engine'"
+
+Make sure di project root saat run script:
+```bash
+cd agriflow_engine
+python examples/run_demo.py
+```
+
+Atau install sebagai package:
+```bash
+pip install -e .  # editable install (kalau pyproject.toml ada)
+```
+
+### Demo crash di Windows: "UnicodeEncodeError: 'charmap' codec"
+
+v10 sudah include UTF-8 fix. Pastikan pakai versi terbaru:
+```bash
+git pull
+```
+
+Atau set env variable manual:
+```bash
+set PYTHONIOENCODING=utf-8
+python examples/run_demo.py
+```
+
+### "FileNotFoundError: sample_data/kabupaten_jatim.csv"
+
+CSV belum di-generate. Run dulu:
+```bash
+python sample_data/generate_sample_data.py
+```
+
+### pytest collect 0 items
+
+Pastikan run dari project root, bukan dari `tests/`:
+```bash
+cd agriflow_engine  # not cd agriflow_engine/tests
+pytest tests/
+```
+
+---
+
+## License & Credits
+
+**Lisensi:** Hackathon submission. Code internal AgriFlow team.
+
+**Credits:**
+- **Algoritma:** Gale-Shapley Stable Matching (Nobel Prize Economics 2012, Roth & Shapley)
+- **Inspirasi platform:** eNAM (India), MealConnect (Feeding America), FEWS NET (USAID), Uber matching pattern, Food Drop Indiana
+- **Data sumber:** Bank Indonesia (PIHPS), Bapanas (Panel Harga), BPS (BRS Desember 2024 IPM), BMKG, PVMBG MAGMA, BNPB DIBI
+
+**Tim AgriFlow:** Hackathon DIGDAYA × PIDI 2026.
+
+**Citing:**
+```
+AgriFlow Team. (2026). AgriFlow Matching Engine v10.0:
+Sub-National Pangan Matching dengan Stable Matching + Equity Multiplier.
+PIDI DIGDAYA × Hackathon 2026, Bank Indonesia.
+```
+
+---
+
+## Pertanyaan & Kontak
+
+- Issue tracker: GitHub Issues (this repo)
+- Proposal lengkap: regenerate via `python docs/generate_v10_docx.py` (output: `docs/AgriFlow_v10.docx`, gitignored)
+- Audit teknis: [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md)
+
+**Deteksi. Prediksi. Distribusi. Untuk Semua.**
+*AgriFlow — Powered by World-First AI Matching Engine for Sub-National Food Distribution.*

README_v11.md

@@ -0,0 +1,692 @@
+---
+title: AgriFlow API
+emoji: "🌾"
+colorFrom: green
+colorTo: yellow
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# AgriFlow Matching Engine
+
+[![tests](https://github.com/masterA88/agriflow_engine/actions/workflows/test.yml/badge.svg)](https://github.com/masterA88/agriflow_engine/actions/workflows/test.yml)
+
+> **v11.0 release notes (Mei 2026)** — this README has been updated for v11. The previous v10 README is preserved at [`README_v10.md`](README_v10.md) for reference / diff.
+>
+> **v11 contains 3 layers of change vs v10** (engine + scenarios + claims):
+> 1. **Engine fix #1** — `volume_score` now uses **coverage-of-demand** (`min(s,d) / demand.volume_tons`) instead of the old `min/max` ratio. Big-producer-to-small-deficit matches (Tuban 800t→Surabaya 100t beras) no longer get unfairly penalized. Demo impact: equity-boost matches (Lamongan→Bangkalan/Sampang beras) now rank **#1 and #2** with FinalScore 100.0 and 98.4 (was #8 in v10).
+> 2. **Engine fix #2** — `MatchResult.segment_multiplier` added. HORECA/GOVERNMENT/INDUSTRIAL demand now get segment-aware adjustments (±10%) based on supply characteristics; final_score = `base × equity × segment`. Fully auditable via per-match flags (`SEGMENT_HORECA_BULK_BONUS`, `SEGMENT_GOVERNMENT_TIER1_BONUS`, etc.). Greedy deficit-ordering also segment-aware.
+> 3. **Scenario expansion 19 → 24** — added C4 multi-holiday calendar (Imlek/Natal/school-start), D6 route blackout (mudik/demo/maintenance), E6 contract reserve (generalisasi Bulog), F1 grade substitution (premium → medium), F2 demand segmentation. New Kategori F: Kualitas & Segmentasi Komersial.
+> 4. **Claim-precision pass** — every diferensiator claim now references `file:line` in `matching_engine/`. Dropped "World-First" / "first-in-world" marketing; replaced with verifiable specifics. Two-tier confidence, +30% equity boost, stable matching — all now scoped to when they actually fire in production.
+>
+> **Test suite: 134/134 pytest pass in 0.42s** (up from v10's 106/106). See [Status & Roadmap](#status--roadmap) for full details. Engine code remains backward-compatible: RETAIL default segment + opt-in `allow_grade_substitution` flag mean existing callers see identical behavior.
+
+---
+
+> **Sub-national pangan matching engine pertama di Indonesia.**
+> Algoritma 4-lapis purpose-built untuk konteks pangan sub-nasional Indonesia. Layer 3 menggabungkan **Modified Gale-Shapley stable matching** (aktif saat kedua kabupaten Tier 1) dengan **greedy multi-objective + equity priority** (aktif saat ada Tier 2 — produksi Jatim saat ini), multi-objective scoring 5 dimensi, dan equity multiplier untuk kabupaten tertinggal IPM <68 saat menjadi deficit — semua untuk komoditas pangan tingkat kabupaten.
+
+[![Tests](https://img.shields.io/badge/tests-106%2F106%20passing-brightgreen)]()
+[![Latency](https://img.shields.io/badge/p99%20latency-1.4ms%20%E2%86%92%2055.5ms-blue)]()
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()
+[![Status](https://img.shields.io/badge/status-provincial--ready-success)]()
+
+Submisi **PIDI DIGDAYA × Hackathon 2026** — Bank Indonesia.
+Problem Statement #2: Platform Matching Demand-Supply Antarwilayah.
+
+---
+
+## Daftar Isi
+
+- [Apa Ini?](#apa-ini)
+- [Quick Start (5 menit)](#quick-start-5-menit)
+- [Arsitektur 4-Lapis](#arsitektur-4-lapis)
+- [Equity Multiplier (Kalibrasi BPS 2024)](#equity-multiplier-kalibrasi-bps-2024)
+- [19 Skenario Edge Case](#19-skenario-edge-case)
+- [API Usage](#api-usage)
+- [Performance & Validation](#performance--validation)
+- [Data Sources](#data-sources)
+- [Project Structure](#project-structure)
+- [Development Guide](#development-guide)
+- [Status & Roadmap](#status--roadmap)
+- [Documentation](#documentation)
+- [License & Credits](#license--credits)
+
+---
+
+## Apa Ini?
+
+**Bayangkan Uber, tapi untuk cabai dan bawang merah.**
+
+Setiap hari, Indonesia kehilangan Rp 213-551 triliun pangan karena food loss & waste — 40% di distribusi, bukan produksi. Petani di Sampang membuang cabai karena harga jatuh, sementara pasar Surabaya melonjak 200% karena kelangkaan. Pemda baru tahu krisis 2-3 minggu kemudian.
+
+AgriFlow Matching Engine memecahkan ini dengan 6 dimensi yang Uber tidak punya:
+
+| Dimensi | Penjelasan |
+|---|---|
+| **Perishability** | Cabai busuk dalam 5 hari, beras tahan 180 hari — engine hitung shelf life |
+| **Equity** | Kabupaten tertinggal IPM <68 dapat boost +30% **saat menjadi deficit/penerima** (allocation.py:38–65). Demo Jatim: Sampang (66.72) + Bangkalan (67.70) trigger `EQUITY_BOOST_30` di 2 dari 32 match (Ngawi→Bangkalan/Sampang beras). Rare-but-correct di Jatim; impact tumbuh dengan rollout nasional (Papua IPM ~50). |
+| **Climate** | Banjir di rute = re-route otomatis |
+| **Volume** | 1 surplus bisa di-split ke banyak deficit |
+| **Stable Matching** | Modified Gale-Shapley (Nobel Prize Economics 2012) — fires saat kedua kabupaten Tier 1 (`allocation.py:341–347`). Untuk Jatim 8-IHK / 30-non-IHK saat ini, supply originate dari Tier 2 → production path = greedy-with-equity-priority. Stable matching jadi load-bearing setelah Tier 1 coverage expand nasional (~90 kota IHK). |
+| **Two-tier Confidence** | Setiap match return label `HIGH` / `MEDIUM` / `LOW` (`allocation.py:68–77`). Di Jatim saat ini MEDIUM adalah label default (semua surplus dari non-IHK kab); HIGH require kedua kab Tier 1 (rare di Jatim, achievable nasional); LOW fires saat data >24h stale. Transparant ke user. |
+| **Climate** | Score penalty saat BMKG/Open-Meteo forecast hujan deras di rute (`scoring.py:130–153`): >50mm/day → 0.3, >20mm → 0.6, ≤20mm → 1.0. Fallback neutral 0.7 untuk rute tanpa forecast data (demo: 10 rute weather seeded). Scoring penalty, bukan re-routing logic. |
+
+**Status:** Production-ready untuk skala provinsial (38 kab Jatim) — **134/134 tests pass** dalam 0.24s, latency p99 1.4ms (sample) - 55.5ms (stress 361×361). **v11.0 (Mei 2026)** adalah *claim-precision + scoring-quality update*:
+1. Claim-precision: setiap klaim diferensiator di proposal sekarang punya referensi spesifik ke `file:line` di `matching_engine/`
+2. **Scoring fix #1** — `volume_score` direvisi dari `min/max` ke `coverage-of-demand`. Big-producer matches (mis. Tuban 800t → Surabaya 100t beras) tidak lagi di-penalize. Hasil demo: equity-boost matches (Lamongan → Bangkalan/Sampang beras) sekarang ranking **#1 dan #2** dengan FinalScore 100.0 dan 98.4 (sebelumnya ranking #8).
+3. **Scoring fix #2** — `segment_multiplier` baru: HORECA/GOVERNMENT/INDUSTRIAL demand sekarang dapat segment-aware bonus (range ±10%) berdasarkan supply characteristics, plus deficit ordering segment-aware. `final_score = base × equity × segment`. Test acid: HORECA wins atas RETAIL di contested-bulk-supply scenario.
+
+24 scenarios coverage tetap 126/126 + 8 new segment/coverage tests = 134/134.
+
+---
+
+## Quick Start (5 menit)
+
+### Prasyarat
+
+- Python 3.10+
+- pip
+- ~50MB disk space
+
+### Install
+
+```bash
+git clone https://github.com/masterA88/agriflow_engine.git
+cd agriflow_engine
+python -m venv venv
+# Windows:
+venv\Scripts\activate
+# Linux/Mac:
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### Verifikasi (semua harus sukses)
+
+```bash
+# 1. Generate sample data — 38 kab × 19 komoditas Jatim
+python sample_data/generate_sample_data.py
+# Expected: 5 CSV generated (kabupaten_jatim.csv, komoditas_constraints.csv,
+#           surplus_deficit.csv, weather_forecast.csv, historical_price_stats.csv)
+
+# 2. Run all tests (106 tests)
+pytest tests/ -v
+# Expected: 106 passed in <1s
+
+# 3. Run end-to-end demo
+python examples/run_demo.py
+# Expected: ~32 matches, gross arbitrage ~Rp 16 miliar, latency ~1.5ms
+
+# 4. Run latency benchmark
+python benchmarks/latency.py
+# Expected: highest p99 < 60ms (margin >88% vs 500ms target)
+```
+
+Kalau langkah 2 atau 3 gagal, lihat [Troubleshooting](#troubleshooting) di bawah.
+
+---
+
+## Arsitektur 4-Lapis
+
+```
+Input: surplus_nodes[], deficit_nodes[], LogisticsContext, weather, historical_prices
+
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 0 — Tier Classification (constraints.determine_tier)      │
+  │   Klasifikasi setiap kab: Tier 1 HIGH (8 kota IHK PIHPS) atau   │
+  │   Tier 2 MEDIUM (30 kab non-IHK Bapanas).                       │
+  │   Latency: <1ms (set lookup).                                   │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 1 — Hard Constraints (constraints.generate_candidates)    │
+  │   9 rules filter: komoditas match, distance≤max, age≤shelf,     │
+  │   volume≥min, no self-match, emergency mode, pemda override,    │
+  │   Bulog split, BBM-aware distance shrink.                       │
+  │   Output: candidate pairs (top-K per surplus by jarak).         │
+  │   Latency: <50ms untuk 38×19 (~25k pasang potensial).           │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 2 — Multi-Objective Scoring (scoring.compute_score)       │
+  │   5-dimensi weighted: Distance 22% / Volume 22% / Price 22% /   │
+  │   Perishability 18% / Climate 16%.                              │
+  │   3 weight schemes: DEFAULT, RAMADAN, IMPORT_POLICY.            │
+  │   Output: base_score 0-100 per pair.                            │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 3 — Equity-Weighted Allocation (allocation.allocate)      │
+  │   Final = base × equity_multiplier(IPM_deficit).                │
+  │   Tier 1↔Tier 1 → Modified Gale-Shapley (Nobel 2012).           │
+  │   Cross-tier / Tier 2 → Greedy with equity priority.            │
+  │   Output: MatchResult[] dengan confidence label.                │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ POST-PROCESSING (engine.run_matching)                           │
+  │   Tag flags (RAMADAN_SPIKE, EQUITY_BOOST_30, MADURA_CLUSTER,    │
+  │   STALE_DATA_24H, HUMANITARIAN_PRIORITY, VOLUME_MISMATCH).      │
+  │   Identifikasi unmatched + external_opportunities (ekspor).     │
+  └─────────────────────────────────────────────────────────────────┘
+
+Output: MatchingReport(matches, unmatched_*, warnings, run_metadata)
+```
+
+**Why 4-layer?** Setiap layer bisa dioptimasi independent, testable secara isolated, dan early-exit di Layer 1 menghemat compute Layer 2/3 yang lebih mahal.
+
+---
+
+## Equity Multiplier (Kalibrasi BPS 2024)
+
+Threshold dikalibrasi sesuai distribusi IPM 2024 BPS Jatim sehingga klaim "+30% boost untuk kab tertinggal" konkret applicable:
+
+| IPM Range | Multiplier | Boost | Kab/Kota Jatim |
+|---|---|---|---|
+| `IPM < 68` | **1.30** | **+30%** | Sampang (66.72), Bangkalan (67.70) |
+| `68 ≤ IPM < 72` | 1.15 | +15% | Sumenep, Probolinggo (kab), Bondowoso, Lumajang, Pamekasan, Pacitan, Pasuruan (kab), Situbondo, Jember, Madiun (kab) |
+| `72 ≤ IPM < 78` | 1.05 | +5% | Bojonegoro, Banyuwangi, Tulungagung, Malang (kab), Magetan, Gresik, Mojokerto (kab), Lamongan, Tuban, Ngawi, Kediri (kab), dll |
+| `IPM ≥ 78` | 1.00 | (no boost) | Sidoarjo, Kota Batu, Kota Surabaya, Kota Malang, Kota Kediri, Kota Madiun, dll |
+
+**Mengapa kalibrasi:** Threshold v9 lama (`<65 → 1.30`) tidak pernah ter-trigger karena IPM terendah Jatim 2024 = Sampang 66.72. v10 menggeser threshold sehingga klaim "+30% boost" demonstrably valid.
+
+**Catatan v11:** Boost +30% applies ke kab IPM <68 **saat menjadi deficit/penerima** (di-multiply dengan `base_score` dari Layer 2 untuk menghasilkan `final_score`). Demo run menunjukkan 2 dari 32 match trigger `EQUITY_BOOST_30` — keduanya Ngawi mengirim beras ke Madura (Bangkalan & Sampang). Saat Sampang sendiri jadi surplus (misal bawang), tidak ada boost karena bukan dia yang menjadi penerima. Honest framing: equity boost menggeser hasil saat low-IPM kab adalah sisi demand, bukan saat low-IPM kab disebutkan saja.
+
+**Update IPM tahunan:** Saat BPS publish IPM baru (biasanya BRS Desember), edit di [`sample_data/generate_sample_data.py:KABUPATEN_DATA`](sample_data/generate_sample_data.py) sebagai source of truth, lalu mirror ke [`data_sources/bps.py:IPM_2024_JATIM`](data_sources/bps.py).
+
+---
+
+## 24 Skenario Edge Case
+
+6 kategori, 24 skenario, semua tervalidasi pytest (126/126). Detail lengkap di [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) dan `AgriFlow_v11.docx` Section 5.5.5. **v11 menambahkan 5 commercial-reality scenarios** (C4 multi-holiday, D6 route blackout, E6 contract reserve, F1 grade substitution, F2 demand segmentation) di atas 19 skenario engineering edge case asli v10.
+
+### Kategori A — Volume (4 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| A1 | Surplus 1-to-many (1 surplus split ke beberapa deficit) | `TestA1_OneToMany` |
+| A2 | Many-to-1 (multiple surplus untuk 1 deficit besar) | `TestA2_ManyToOne` |
+| A3 | Volume mismatch drastis (<20% ratio → flag warning) | `TestA3_VolumeMismatchDrastis` |
+| A4 | Zero demand (suggest external opportunity) | `TestA4_ZeroDemand` |
+
+### Kategori B — Spasial (3 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| B1 | Cross-tier match (Tier 1 ↔ Tier 2) | `TestB1_CrossTier` |
+| B2 | Long distance (jarak > max_distance_km → REJECT) | `TestB2_LongDistance` |
+| B3 | Cluster Madura (4 kab semua surplus → ekspor) | `TestB3_ClusterMadura` |
+
+### Kategori C — Temporal (4 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| C1 | Ramadan/Idul Fitri spike (H-21 to H-1, RAMADAN_WEIGHTS) | `TestC1_RamadanSpike` |
+| C2 | Pasca panen raya (oversupply, multiple match) | `TestC2_PostHarvest` |
+| C3 | Stale data >24h (confidence drop bertingkat HIGH→MEDIUM→LOW) | `TestC3_StaleData` |
+| **C4** | **Multi-holiday calendar (Imlek H-7, Natal H-21, school-start H-14)** dengan weight profile per event | `TestC4_HolidayCalendar` |
+
+### Kategori D — Disrupsi (6 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| D1 | Banjir rute (BMKG hujan >50mm → climate_score 0.3) | `TestD1_BanjirRute` |
+| D2 | Komoditas hampir rusak (harvest age + transit > shelf) | `TestD2_KomoditasRusak` |
+| D3 | Harga anomali (>3σ dari rolling median → exclude) | `TestD3_HargaAnomali` |
+| D4 | Erupsi gunung (PVMBG MAGMA → UNREACHABLE) | `TestD4_ErupsiGunung` |
+| D5 | Banjir multi-kab (BNPB DIBI → emergency mode) | `TestD5_BanjirMultiKab` |
+| **D6** | **Route blackout (mudik H+1 Idul Fitri, demo Trans-Jawa, Suramadu maintenance)** dengan wildcard support | `TestD6_RouteBlackout` |
+
+### Kategori E — Politis & Kebijakan (6 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| E1 | Equity tie-break (IPM lebih rendah menang otomatis) | `TestE1_EquityTieBreak` |
+| E2 | Pemda override (`do_not_export_<komoditas>` flag) | `TestE2_PemdaOverride` |
+| E3 | Bulog priority (60% reserve, sisa 40% private) | `TestE3_BulogPriority` |
+| E4 | Import policy aktif (IMPORT_POLICY_WEIGHTS, price weight ↓) | `TestE4_ImportPolicy` |
+| E5 | BBM naik (max_distance shrink, logistics cost ↑) | `TestE5_BBMNaik` |
+| **E6** | **Contract reserve generalisasi (Carrefour MoU 70%, Indofood gula 50%, dll)** — Bulog pattern di-generalisir | `TestE6_ContractReserve` |
+
+### Kategori F — Kualitas & Segmentasi Komersial (2 skenario, NEW v11)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| **F1** | **Grade substitution** — surplus `beras_premium` dapat memenuhi demand `beras_medium` (opt-in `allow_grade_substitution=True`); reverse direction tetap REJECT | `TestF1_GradeSubstitution` |
+| **F2** | **Demand segmentation** — `RETAIL` / `HORECA` / `GOVERNMENT` / `INDUSTRIAL` coexist untuk kab + komoditas yang sama; tiap segment di-match independen dengan flag `SEGMENT_<NAME>` | `TestF2_DemandSegmentation` |
+
+---
+
+## API Usage
+
+### Programmatic API
+
+```python
+from matching_engine import (
+    run_matching, SupplyNode, DemandNode,
+    Kabupaten, Tier, Commodity, LogisticsContext,
+)
+
+# Setup kabupaten (real koordinat & IPM 2024 BPS)
+kediri = Kabupaten(
+    id="3506", nama="Kediri",
+    latitude=-7.796, longitude=112.170,
+    ipm=74.50, tier=Tier.MEDIUM,
+)
+surabaya = Kabupaten(
+    id="3578", nama="Kota Surabaya",
+    latitude=-7.2575, longitude=112.7521,
+    ipm=84.69, tier=Tier.HIGH,
+)
+
+# Setup komoditas (constraint per komoditas)
+cabai = Commodity(
+    code="cabai_merah", nama="Cabai Merah Besar",
+    max_distance_km=200, min_viable_tons=1.0,
+    max_fresh_age_days=5,
+)
+
+# Run matching
+report = run_matching(
+    surplus_nodes=[
+        SupplyNode(kediri, cabai, volume_tons=80, price_per_kg=30000),
+    ],
+    deficit_nodes=[
+        DemandNode(surabaya, cabai, volume_tons=80, price_per_kg=60000),
+    ],
+    logistics=LogisticsContext(),
+)
+
+# Inspect hasil
+for m in report.matches:
+    print(f"{m.surplus.kabupaten.nama} → {m.deficit.kabupaten.nama}")
+    print(f"  Volume: {m.matched_volume_tons}t @ {m.distance_km:.0f}km")
+    print(f"  Score: {m.final_score:.1f} (base {m.base_score:.1f} × {m.equity_multiplier})")
+    print(f"  Confidence: {m.confidence.value}, Flags: {m.flags}")
+    # Realistic output dari demo Jatim:
+    #   Probolinggo → Kota Surabaya: 120.0t Bawang Merah
+    #   Score: 89.5 (base 89.5 × 1.00), Confidence: MEDIUM, Flags: []
+    #   Bangkalan → Gresik: 40.0t Bawang Merah
+    #   Score: 89.4 (base 85.1 × 1.05), Confidence: MEDIUM, Flags: ['EQUITY_BOOST_05', 'MADURA_CLUSTER']
+    #   Ngawi → Bangkalan: 250.0t Beras Premium
+    #   Score: 82.8 (base 63.7 × 1.30), Confidence: MEDIUM, Flags: ['EQUITY_BOOST_30', 'MADURA_CLUSTER']
+
+# Output:
+# Kediri → Kota Surabaya
+#   Volume: 80.0t @ 65km
+#   Score: 89.5 (base 89.5 × 1.0)
+#   Confidence: MEDIUM, Flags: []
+
+print(f"\nLatency: {report.run_metadata['latency_ms']}ms")
+print(f"Candidate pairs evaluated: {report.run_metadata['candidate_pairs_evaluated']}")
+print(f"Warnings: {len(report.warnings)}")
+```
+
+### Advanced — Skenario Override
+
+```python
+from matching_engine.constraints import set_bulog_procurement
+from datetime import datetime
+
+# Skenario E3: Bulog procurement aktif untuk Madiun
+set_bulog_procurement({"3519"})
+
+# Skenario E4: Import policy aktif (bobot price diturunkan)
+report = run_matching(
+    surplus_nodes=[...],
+    deficit_nodes=[...],
+    import_policy_active=True,  # IMPORT_POLICY_WEIGHTS
+)
+
+# Skenario C1: Force Ramadan mode untuk testing
+report = run_matching(
+    surplus_nodes=[...],
+    deficit_nodes=[...],
+    reference_date=datetime(2026, 3, 6),  # H-14 Idul Fitri 2026
+)
+
+# Skenario E5: BBM naik 20%
+from matching_engine.models import LogisticsContext
+report = run_matching(
+    surplus_nodes=[...],
+    deficit_nodes=[...],
+    logistics=LogisticsContext(
+        bbm_price_idr_per_liter=12000,
+        bbm_price_baseline=10000,
+    ),
+)
+```
+
+### Advanced — Force Algorithm Strategy
+
+```python
+# Force stable matching (Tier 1 algorithm)
+report = run_matching(..., force_strategy="stable")
+
+# Force greedy (Tier 2 algorithm) untuk testing
+report = run_matching(..., force_strategy="greedy")
+
+# Auto-detect (default): Tier 1↔Tier 1 pairs → stable, else → greedy
+report = run_matching(...)
+```
+
+---
+
+## Performance & Validation
+
+### Test Suite
+
+```bash
+$ pytest tests/ --tb=short
+============================= test session starts =============================
+collected 106 items
+
+tests/test_layer0_tier.py ................                           [ 15%]
+tests/test_layer1_constraints.py ...................                 [ 33%]
+tests/test_layer2_scoring.py .......................                 [ 54%]
+tests/test_layer3_allocation.py ..............                       [ 67%]
+tests/test_scenarios_disruption.py .........                         [ 76%]
+tests/test_scenarios_political.py ........                           [ 83%]
+tests/test_scenarios_spatial.py ......                               [ 89%]
+tests/test_scenarios_temporal.py .......                             [ 96%]
+tests/test_scenarios_volume.py ....                                  [100%]
+
+============================= 106 passed in 0.16s =============================
+```
+
+### Latency Benchmark
+
+```bash
+$ python benchmarks/latency.py
+```
+
+| Configuration | N (s × d) | p50 | p95 | p99 | Max |
+|---|---|---|---|---|---|
+| Sample data CSV (realistic) | 40 × 33 | 0.99 ms | 1.26 ms | 1.38 ms | 1.42 ms |
+| Synthetic full Jatim (38×19) | 361 × 361 | 48.37 ms | 53.67 ms | 55.53 ms | 58.43 ms |
+| Stress 100×100 (national scale) | 100 × 100 | 12.62 ms | 14.82 ms | 15.51 ms | 15.65 ms |
+| Stress 200×200 | 200 × 200 | 25.47 ms | 26.92 ms | 27.54 ms | 27.76 ms |
+
+**Verdict:** PASS — semua p99 < 500ms target. Highest p99 = 55.53ms (margin 88.9%).
+
+### National Scale (Indonesia 514 kab)
+
+⚠ **HONEST DISCLOSURE:** Engine v11 (sama dengan v10 — claim-precision pass, bukan engine change) saat ini BELUM siap untuk produksi nasional 514 kab. Lihat [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) Section 3.2 untuk detail. Optimization roadmap (spatial indexing, per-provinsi batching, parallel) sudah ter-quantify untuk Y2-Y3.
+
+```bash
+$ python benchmarks/national_scale.py
+```
+
+| Scale | Workload | p99 | vs target |
+|---|---|---|---|
+| Provinsi Jatim baseline | 333×389 | **14.2ms** | ✅ 35× under |
+| Multi-provinsi (100 kab) | 948×952 | **94.5ms** | ✅ 5× under |
+| Setengah Indonesia (250 kab) | 2326×2424 | **541.8ms** | ⚠ 1.08× over |
+| **Full Indonesia (514 kab)** | **4859×4907** | **2223.3ms** | ❌ **4.4× over** |
+
+---
+
+## Data Sources
+
+8 connector dengan dual-mode (mock CSV + live API), graceful fallback:
+
+| Connector | Sumber | Frekuensi | Auth | Tier |
+|---|---|---|---|---|
+| [`pihps_bi.py`](data_sources/pihps_bi.py) | Bank Indonesia PIHPS | Harian (cut-off 13:00 WIB) | Tidak ada (scrape publik) | Tier 1 |
+| [`bapanas.py`](data_sources/bapanas.py) | Panel Harga Bapanas | Mingguan (Senin) | Tidak ada | Tier 2 |
+| [`bps.py`](data_sources/bps.py) | BPS WebAPI (IPM, produksi) | Tahunan (BRS Desember) | API key gratis | Both |
+| [`bmkg.py`](data_sources/bmkg.py) | BMKG / Open-Meteo (cuaca) | 3-6 jam refresh | Tidak ada (Open-Meteo) | Both |
+| [`pvmbg.py`](data_sources/pvmbg.py) | PVMBG MAGMA (gunung api) | Realtime saat status berubah | Tidak ada | Both |
+| [`bnpb.py`](data_sources/bnpb.py) | BNPB DIBI (bencana) | Realtime | Tidak ada | Both |
+| [`google_maps.py`](data_sources/google_maps.py) | Google Routes / OSRM fallback | Realtime per request | Google API key (paid) / OSRM gratis | Both |
+| [`hijri_calendar.py`](data_sources/hijri_calendar.py) | Aladhan API + hardcoded | Statis | Tidak ada | Both |
+
+### Fail-safe Strategy
+
+- Live API gagal → fallback ke mock CSV / hardcoded data
+- Weather data tidak tersedia → climate_score = 0.7 (neutral)
+- BPS API gagal → fallback ke `IPM_2024_JATIM` hardcoded
+- BMKG butuh adm4 mapping yang tidak ada → auto-fallback ke Open-Meteo
+- OSRM down → haversine geodesic + asumsi 60 km/h
+
+---
+
+## Project Structure
+
+```
+agriflow_engine/
+├── matching_engine/         # Core engine (5 modules, ~1000 lines)
+│   ├── __init__.py          # Public API
+│   ├── models.py            # Dataclasses (Kabupaten, Commodity, MatchResult, ...)
+│   ├── constraints.py       # Layer 0 + Layer 1 (9 hard constraints)
+│   ├── scoring.py           # Layer 2 (5-dim multi-objective scoring)
+│   ├── allocation.py        # Layer 3 (Gale-Shapley + Greedy + Equity)
+│   └── engine.py            # Main orchestrator + 19 skenario handlers
+├── data_sources/            # 8 connector dual-mode (mock + live)
+│   ├── pihps_bi.py          # Tier 1 PIHPS BI
+│   ├── bapanas.py           # Tier 2 Bapanas
+│   ├── bps.py               # IPM 2024 + produksi BPS
+│   ├── bmkg.py              # Cuaca BMKG/Open-Meteo
+│   ├── pvmbg.py             # Erupsi gunung PVMBG MAGMA
+│   ├── bnpb.py              # Bencana BNPB DIBI
+│   ├── google_maps.py       # Routing Google/OSRM
+│   └── hijri_calendar.py    # Ramadan/Idul Fitri Aladhan
+├── sample_data/             # CSV 38 kab × 19 komoditas Jatim
+│   ├── generate_sample_data.py  # Source of truth — regenerate CSV
+│   ├── loader.py                # CSV → engine objects
+│   ├── kabupaten_jatim.csv      # 38 kab + IPM 2024 + koordinat
+│   ├── komoditas_constraints.csv  # 19 komoditas + spec
+│   ├── surplus_deficit.csv      # 73 row sample workload
+│   ├── weather_forecast.csv     # 10 route forecast
+│   └── historical_price_stats.csv  # 19 commodity rolling stats
+├── tests/                   # 106 pytest test
+│   ├── conftest.py          # Fixtures (17 kab Jatim + factory)
+│   ├── test_layer0_tier.py             # 16 test (tier classification)
+│   ├── test_layer1_constraints.py      # 19 test (haversine + viability + Bulog)
+│   ├── test_layer2_scoring.py          # 23 test (5-dim scoring + weight schemes)
+│   ├── test_layer3_allocation.py       # 14 test (equity + stable + greedy)
+│   ├── test_scenarios_volume.py        # 4 test (A1-A4)
+│   ├── test_scenarios_spatial.py       # 6 test (B1-B3)
+│   ├── test_scenarios_temporal.py      # 7 test (C1-C3)
+│   ├── test_scenarios_disruption.py    # 9 test (D1-D5)
+│   └── test_scenarios_political.py     # 8 test (E1-E5)
+├── examples/
+│   └── run_demo.py          # End-to-end demo dengan output formatted
+├── benchmarks/
+│   ├── latency.py           # Multi-config provincial benchmark
+│   └── national_scale.py    # National scale stress test (514 kab)
+├── docs/
+│   ├── generate_v11_docx.py # Proposal v11 docx generator (claim-precision pass; current)
+│   ├── generate_v10_docx.py # Proposal v10 docx generator (history)
+│   └── AUDIT_v10.md         # Audit lengkap (consistency + national scale analysis)
+├── README.md                # This file
+├── requirements.txt         # Python dependencies
+└── venv/                    # (gitignored) virtual env
+```
+
+---
+
+## Development Guide
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/masterA88/agriflow_engine.git
+cd agriflow_engine
+python -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -r requirements.txt
+pip install python-docx  # untuk regenerate proposal docx
+```
+
+### Workflow
+
+1. **Edit code** di `matching_engine/` atau `data_sources/`
+2. **Run test** sebelum commit: `pytest tests/ -v`
+3. **Update sample data** kalau ubah threshold/komoditas: `python sample_data/generate_sample_data.py`
+4. **Run demo** untuk smoke test: `python examples/run_demo.py`
+5. **Run benchmark** kalau perubahan di hot path: `python benchmarks/latency.py`
+6. **Regenerate proposal** kalau perubahan di logic: `python docs/generate_v10_docx.py`
+
+### Add New Skenario
+
+1. Tambah test class di file yang sesuai (mis. `tests/test_scenarios_volume.py`)
+2. Tambah behavior di `matching_engine/engine.py` post-processing atau Layer yang relevan
+3. Update `AgriFlow_v10.docx` Section 5.5.5 (regenerate via `docs/generate_v10_docx.py`)
+4. Pastikan `pytest tests/ -v` masih PASS
+
+### Add New Komoditas
+
+1. Tambah row di [`sample_data/generate_sample_data.py:KOMODITAS_DATA`](sample_data/generate_sample_data.py)
+2. Tambah row di [`matching_engine/constraints.py:COMMODITY_SPECS`](matching_engine/constraints.py) (samakan max_distance/min_viable/max_fresh_age)
+3. Run `python sample_data/generate_sample_data.py` untuk regenerate CSV
+4. Update assertion di test kalau komoditas count check
+
+### Update IPM Tahunan (saat BPS publish data baru)
+
+1. Edit [`sample_data/generate_sample_data.py:KABUPATEN_DATA`](sample_data/generate_sample_data.py) (source of truth)
+2. Mirror ke [`data_sources/bps.py:IPM_2024_JATIM`](data_sources/bps.py)
+3. Run `python sample_data/generate_sample_data.py` untuk regenerate CSV
+4. Re-evaluate equity threshold di [`matching_engine/allocation.py:38`](matching_engine/allocation.py) — apakah masih meaningful trigger untuk distribusi baru?
+5. Run `pytest tests/ -v` — beberapa test mungkin perlu update kalau IPM bergeser
+
+---
+
+## Status & Roadmap
+
+### Current Status: ✅ Provincial-Ready (Jatim)
+
+- [x] 4-layer architecture implemented
+- [x] 19 skenario edge case handled
+- [x] 106/106 tests passing
+- [x] Latency p99 1.4ms (sample) - 55.5ms (stress)
+- [x] Equity multiplier kalibrasi BPS 2024 — Sampang & Bangkalan menerima +30% boost
+- [x] 8 data source connector dual-mode
+- [x] Cross-platform demo (Windows/Linux/Mac)
+- [x] Reproducible documentation generator
+
+### Roadmap to National Scale (Y2-Y3)
+
+⚠ **Honest disclosure:** Engine v11 (sama core dengan v10) saat ini BELUM siap untuk produksi nasional 514 kab. p99 untuk full Indonesia = 2.2 detik (4.4× over 500ms target).
+
+**Optimization plan** (lihat [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) Section 6):
+
+| Quick Win | Effort | Impact |
+|---|---|---|
+| Fix double-haversine bug di `generate_candidates` | 1 jam | 30-40% speedup Layer 1 |
+| Add geohash precision-5 spatial pre-filter | 1-2 hari | 25-50× speedup Layer 1 |
+| Multiprocessing per komoditas | 2-3 hari | Up to 19× speedup |
+| Distance matrix precompute (Redis cache) | 4 jam | 5-10× speedup |
+| Per-provinsi batching | 1 minggu | 5-15× speedup |
+
+**Combined estimate:** ~100-200× speedup → bring p99 dari 2200ms ke ~10-20ms untuk 514 kab nasional.
+
+### Data/Coverage Expansion (Y2)
+
+- [ ] `TIER_1_KOTA_IHK`: 8 kota Jatim → ~90 kota IHK Indonesia
+- [ ] `IPM_2024_JATIM` → `IPM_2024_INDONESIA` (514 kab/kota)
+- [ ] Cluster definitions: Madura → 10-20 cluster nasional
+- [ ] `GUNUNG_KABUPATEN_MAP`: 6 gunung Jatim → 130+ gunung api Indonesia
+- [ ] Sample data: 38 kab → 514 kab synthetic + real
+
+### Architectural Expansion (Y2-Y3)
+
+- [ ] Inter-island logistics (transport mode: truck/ferry/cargo plane)
+- [ ] Equity threshold recalibration nasional (range IPM 50-85)
+- [ ] CI/CD pipeline (GitHub Actions: pytest + benchmark assertions)
+- [ ] FastAPI wrapper untuk REST API production
+- [ ] Hybrid stable+greedy untuk skenario campuran tier
+- [ ] LLM integration (Gemini + Sahabat-AI Bahasa Daerah)
+
+---
+
+## Documentation
+
+| Document | Lokasi | Deskripsi |
+|---|---|---|
+| **Proposal v11** (current) | Generate via `python docs/generate_v11_docx.py` | Proposal lengkap dengan claim-precision pass — setiap klaim diferensiator dirujuk ke `file:line` di `matching_engine/` (docx gitignored — internal team artifact) |
+| **Proposal v10** (history) | Generate via `python docs/generate_v10_docx.py` | Versi sebelum claim-precision pass; tetap dipertahankan sebagai history |
+| **Audit v10** | [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) | Consistency check + national scale analysis (engine code identik di v11) |
+| **README** | This file | Quick reference + getting started |
+| **Generator script** | [`docs/generate_v11_docx.py`](docs/generate_v11_docx.py) | Regenerate proposal v11 docx dari source |
+| **Code comments** | All `.py` files | Inline docstrings dengan reference ke proposal section |
+
+---
+
+## Troubleshooting
+
+### "ModuleNotFoundError: No module named 'matching_engine'"
+
+Make sure di project root saat run script:
+```bash
+cd agriflow_engine
+python examples/run_demo.py
+```
+
+Atau install sebagai package:
+```bash
+pip install -e .  # editable install (kalau pyproject.toml ada)
+```
+
+### Demo crash di Windows: "UnicodeEncodeError: 'charmap' codec"
+
+v10 sudah include UTF-8 fix. Pastikan pakai versi terbaru:
+```bash
+git pull
+```
+
+Atau set env variable manual:
+```bash
+set PYTHONIOENCODING=utf-8
+python examples/run_demo.py
+```
+
+### "FileNotFoundError: sample_data/kabupaten_jatim.csv"
+
+CSV belum di-generate. Run dulu:
+```bash
+python sample_data/generate_sample_data.py
+```
+
+### pytest collect 0 items
+
+Pastikan run dari project root, bukan dari `tests/`:
+```bash
+cd agriflow_engine  # not cd agriflow_engine/tests
+pytest tests/
+```
+
+---
+
+## License & Credits
+
+**Lisensi:** Hackathon submission. Code internal AgriFlow team.
+
+**Credits:**
+- **Algoritma:** Modified Gale-Shapley Stable Matching (Nobel Prize Economics 2012, Roth & Shapley) — fires saat kedua kab Tier 1; Greedy multi-objective + equity priority untuk Tier 2 dan cross-tier
+- **Inspirasi platform:** eNAM (India), MealConnect (Feeding America), FEWS NET (USAID), Uber matching pattern, Food Drop Indiana
+- **Data sumber:** Bank Indonesia (PIHPS), Bapanas (Panel Harga), BPS (BRS Desember 2024 IPM), BMKG, PVMBG MAGMA, BNPB DIBI
+
+**Tim AgriFlow:** Hackathon DIGDAYA × PIDI 2026.
+
+**Citing:**
+```
+AgriFlow Team. (2026). AgriFlow Matching Engine v11.0:
+Purpose-Built Sub-National Indonesian Food Matching Engine
+dengan Stable Matching (Tier 1) + Greedy-Equity-Priority (Tier 2) + IPM-Based Equity Multiplier (BPS 2024).
+PIDI DIGDAYA × Hackathon 2026, Bank Indonesia.
+```
+
+---
+
+## Pertanyaan & Kontak
+
+- Issue tracker: GitHub Issues (this repo)
+- Proposal lengkap: regenerate via `python docs/generate_v10_docx.py` (output: `docs/AgriFlow_v10.docx`, gitignored)
+- Audit teknis: [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md)
+
+**Deteksi. Prediksi. Distribusi. Untuk Semua.**
+*AgriFlow — Purpose-Built Sub-National AI Matching Engine for Indonesian Food Distribution.*

README_v12.md

@@ -0,0 +1,729 @@
+---
+title: AgriFlow API
+emoji: "🌾"
+colorFrom: green
+colorTo: yellow
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# AgriFlow Matching Engine
+
+[![tests](https://github.com/masterA88/agriflow_engine/actions/workflows/test.yml/badge.svg)](https://github.com/masterA88/agriflow_engine/actions/workflows/test.yml)
+
+> **v12.0 release notes (Mei 2026)** — engine hardening + empirical equity validation di atas v11. README v11 diarsipkan di [`README_v11.md`](README_v11.md) (scoring/scenario history v11 disimpan di sana).
+>
+> **v12 = engine-hardening + empirical-validation pass vs v11:**
+> 1. **OSRM road-distance precompute** — Layer 1 sekarang prefer OSRM road distance (`sample_data/road_distance_jatim.csv`, 38×38=1444 pairs) di atas haversine. Haversine over-permissive: **18.6% pair false-positive viable** untuk komoditas MAX_DISTANCE=200km (detour Selat Madura). Fallback haversine untuk pair tak dikenal.
+> 2. **Concurrency hardening** — `BULOG_PROCUREMENT_KAB` tidak lagi race; `run_matching`/`apply_bulog_split` terima param eksplisit `bulog_procurement_kab` (regression test 100 parallel run × 4 worker).
+> 3. **Layer 1 perf** — duplicate haversine dieliminasi; ~30% Layer 1 speedup, end-to-end mean −7–13%.
+> 4. **CI** — GitHub Actions pytest matrix (Ubuntu+Windows × Python 3.11/3.12) + benchmark publish.
+> 5. **Empirical equity validation** — baseline comparison vs pure-greedy / uniform / proportional, dua rezim pasokan (lihat [Validasi Empiris Equity](#validasi-empiris-equity-baseline-comparison)). **Temuan kunci (jujur):** di pasokan melimpah, equity nyaris tak terlihat (kab termiskin sudah terlayani; Gini AgriFlow ≈ greedy). Saat langka (shock La Nina), greedy menelantarkan Sampang (0%)/Bangkalan (20%) sedangkan **AgriFlow jamin keduanya 100% dengan biaya coverage agregat NOL** — inilah nilai equity yang sebenarnya, terukur. Klaim presisi: "memprioritaskan kab terlemah saat pasokan langka", bukan "menurunkan Gini secara umum".
+> 6. **Claim reframe** — "Gale-Shapley stable matching (Nobel 2012)" → **centralized bipartite assignment dengan equity weighting** (preferences kedua sisi berasal dari shared welfare score; Gale-Shapley dipakai sebagai operational primitive, cf. Galichon 2021).
+>
+> **Test suite: 205/205 pytest pass** (naik dari v11's 134; +baseline-comparison +constrained-scenario +road-distance +concurrency). Engine backward-compatible: param baru `equity_fn` default ke fungsi shipped, `road_distance_km` fallback ke haversine.
+
+---
+
+> **Sub-national pangan matching engine pertama di Indonesia.**
+> Algoritma 4-lapis purpose-built untuk konteks pangan sub-nasional Indonesia. Layer 3 menggabungkan **Gale-Shapley sebagai operational primitive** untuk centralized bipartite assignment dengan equity weighting (aktif saat kedua kabupaten Tier 1; cf. Galichon 2021) dengan **greedy multi-objective + equity priority** (aktif saat ada Tier 2 — produksi Jatim saat ini), multi-objective scoring 5 dimensi, dan equity multiplier untuk kabupaten tertinggal IPM <68 saat menjadi deficit — semua untuk komoditas pangan tingkat kabupaten.
+
+[![Tests](https://img.shields.io/badge/tests-205%2F205%20passing-brightgreen)]()
+[![Latency](https://img.shields.io/badge/p99%20latency-1.4ms%20%E2%86%92%2055.5ms-blue)]()
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()
+[![Status](https://img.shields.io/badge/status-provincial--ready-success)]()
+
+Submisi **PIDI DIGDAYA × Hackathon 2026** — Bank Indonesia.
+Problem Statement #2: Platform Matching Demand-Supply Antarwilayah.
+
+---
+
+## Daftar Isi
+
+- [Apa Ini?](#apa-ini)
+- [Quick Start (5 menit)](#quick-start-5-menit)
+- [Arsitektur 4-Lapis](#arsitektur-4-lapis)
+- [Equity Multiplier (Kalibrasi BPS 2024)](#equity-multiplier-kalibrasi-bps-2024)
+- [19 Skenario Edge Case](#19-skenario-edge-case)
+- [API Usage](#api-usage)
+- [Performance & Validation](#performance--validation)
+- [Validasi Empiris Equity](#validasi-empiris-equity-baseline-comparison)
+- [Data Sources](#data-sources)
+- [Project Structure](#project-structure)
+- [Development Guide](#development-guide)
+- [Status & Roadmap](#status--roadmap)
+- [Documentation](#documentation)
+- [License & Credits](#license--credits)
+
+---
+
+## Apa Ini?
+
+**Bayangkan Uber, tapi untuk cabai dan bawang merah.**
+
+Setiap hari, Indonesia kehilangan Rp 213-551 triliun pangan karena food loss & waste — 40% di distribusi, bukan produksi. Petani di Sampang membuang cabai karena harga jatuh, sementara pasar Surabaya melonjak 200% karena kelangkaan. Pemda baru tahu krisis 2-3 minggu kemudian.
+
+AgriFlow Matching Engine memecahkan ini dengan 6 dimensi yang Uber tidak punya:
+
+| Dimensi | Penjelasan |
+|---|---|
+| **Perishability** | Cabai busuk dalam 5 hari, beras tahan 180 hari — engine hitung shelf life |
+| **Equity** | Kabupaten tertinggal IPM <68 dapat boost +30% **saat menjadi deficit/penerima** (allocation.py:38–65). Demo Jatim: Sampang (66.72) + Bangkalan (67.70) trigger `EQUITY_BOOST_30` di 2 dari 32 match (Ngawi→Bangkalan/Sampang beras). Rare-but-correct di Jatim; impact tumbuh dengan rollout nasional (Papua IPM ~50). |
+| **Climate** | Banjir di rute = re-route otomatis |
+| **Volume** | 1 surplus bisa di-split ke banyak deficit |
+| **Centralized Assignment** | Gale-Shapley sebagai *operational primitive* untuk centralized bipartite assignment dengan equity weighting — fires saat kedua kabupaten Tier 1 (`allocation.py:341–347`). Preferences kedua sisi berasal dari shared welfare score, jadi ini bukan two-sided matching market dengan preferensi independen (cf. Galichon 2021). Untuk Jatim 8-IHK / 30-non-IHK saat ini, supply originate dari Tier 2 → production path = greedy-with-equity-priority. |
+| **Two-tier Confidence** | Setiap match return label `HIGH` / `MEDIUM` / `LOW` (`allocation.py:68–77`). Di Jatim saat ini MEDIUM adalah label default (semua surplus dari non-IHK kab); HIGH require kedua kab Tier 1 (rare di Jatim, achievable nasional); LOW fires saat data >24h stale. Transparant ke user. |
+| **Climate** | Score penalty saat BMKG/Open-Meteo forecast hujan deras di rute (`scoring.py:130–153`): >50mm/day → 0.3, >20mm → 0.6, ≤20mm → 1.0. Fallback neutral 0.7 untuk rute tanpa forecast data (demo: 10 rute weather seeded). Scoring penalty, bukan re-routing logic. |
+
+**Status:** Production-ready untuk skala provinsial (38 kab Jatim) — **205/205 tests pass** dalam ~1.4s, latency p99 1.4ms (sample) - 55.5ms (stress 361×361). **v12.0 (Mei 2026)** adalah *engine-hardening + empirical-equity-validation update* di atas v11 (claim-precision + scoring-quality):
+1. **OSRM road-distance** menggantikan haversine di Layer 1 (haversine over-permissive: 18.6% false-positive viable untuk komoditas 200km).
+2. **Concurrency + perf + CI** — BULOG race fixed, double-haversine dieliminasi (~30% Layer 1 speedup), GitHub Actions matrix.
+3. **Empirical equity validation** — baseline comparison membuktikan nilai equity AgriFlow muncul saat pasokan **langka** (greedy telantarkan Sampang 0%/Bangkalan 20%; AgriFlow jamin 100% biaya nol), bukan saat melimpah. Klaim Gale-Shapley di-reframe ke *centralized bipartite assignment* (cf. Galichon 2021). Lihat [Validasi Empiris Equity](#validasi-empiris-equity-baseline-comparison).
+
+205/205 = 134 (v11) + baseline-comparison + constrained-scenario + road-distance + concurrency tests.
+
+---
+
+## Quick Start (5 menit)
+
+### Prasyarat
+
+- Python 3.10+
+- pip
+- ~50MB disk space
+
+### Install
+
+```bash
+git clone https://github.com/masterA88/agriflow_engine.git
+cd agriflow_engine
+python -m venv venv
+# Windows:
+venv\Scripts\activate
+# Linux/Mac:
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### Verifikasi (semua harus sukses)
+
+```bash
+# 1. Generate sample data — 38 kab × 19 komoditas Jatim
+python sample_data/generate_sample_data.py
+# Expected: 5 CSV generated (kabupaten_jatim.csv, komoditas_constraints.csv,
+#           surplus_deficit.csv, weather_forecast.csv, historical_price_stats.csv)
+
+# 2. Run all tests (205 tests)
+pytest tests/ -v
+# Expected: 205 passed in ~1.4s
+
+# 3. Run end-to-end demo
+python examples/run_demo.py
+# Expected: ~32 matches, gross arbitrage ~Rp 16 miliar, latency ~1.5ms
+
+# 4. Run latency benchmark
+python benchmarks/latency.py
+# Expected: highest p99 < 60ms (margin >88% vs 500ms target)
+```
+
+Kalau langkah 2 atau 3 gagal, lihat [Troubleshooting](#troubleshooting) di bawah.
+
+---
+
+## Arsitektur 4-Lapis
+
+```
+Input: surplus_nodes[], deficit_nodes[], LogisticsContext, weather, historical_prices
+
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 0 — Tier Classification (constraints.determine_tier)      │
+  │   Klasifikasi setiap kab: Tier 1 HIGH (8 kota IHK PIHPS) atau   │
+  │   Tier 2 MEDIUM (30 kab non-IHK Bapanas).                       │
+  │   Latency: <1ms (set lookup).                                   │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 1 — Hard Constraints (constraints.generate_candidates)    │
+  │   9 rules filter: komoditas match, distance≤max, age≤shelf,     │
+  │   volume≥min, no self-match, emergency mode, pemda override,    │
+  │   Bulog split, BBM-aware distance shrink.                       │
+  │   Output: candidate pairs (top-K per surplus by jarak).         │
+  │   Latency: <50ms untuk 38×19 (~25k pasang potensial).           │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 2 — Multi-Objective Scoring (scoring.compute_score)       │
+  │   5-dimensi weighted: Distance 22% / Volume 22% / Price 22% /   │
+  │   Perishability 18% / Climate 16%.                              │
+  │   3 weight schemes: DEFAULT, RAMADAN, IMPORT_POLICY.            │
+  │   Output: base_score 0-100 per pair.                            │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ LAYER 3 — Equity-Weighted Allocation (allocation.allocate)      │
+  │   Final = base × equity_multiplier(IPM_deficit).                │
+  │   Tier 1↔Tier 1 → Modified Gale-Shapley (Nobel 2012).           │
+  │   Cross-tier / Tier 2 → Greedy with equity priority.            │
+  │   Output: MatchResult[] dengan confidence label.                │
+  └─────────────────────────────────────────────────────────────────┘
+                            ↓
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ POST-PROCESSING (engine.run_matching)                           │
+  │   Tag flags (RAMADAN_SPIKE, EQUITY_BOOST_30, MADURA_CLUSTER,    │
+  │   STALE_DATA_24H, HUMANITARIAN_PRIORITY, VOLUME_MISMATCH).      │
+  │   Identifikasi unmatched + external_opportunities (ekspor).     │
+  └─────────────────────────────────────────────────────────────────┘
+
+Output: MatchingReport(matches, unmatched_*, warnings, run_metadata)
+```
+
+**Why 4-layer?** Setiap layer bisa dioptimasi independent, testable secara isolated, dan early-exit di Layer 1 menghemat compute Layer 2/3 yang lebih mahal.
+
+---
+
+## Equity Multiplier (Kalibrasi BPS 2024)
+
+Threshold dikalibrasi sesuai distribusi IPM 2024 BPS Jatim sehingga klaim "+30% boost untuk kab tertinggal" konkret applicable:
+
+| IPM Range | Multiplier | Boost | Kab/Kota Jatim |
+|---|---|---|---|
+| `IPM < 68` | **1.30** | **+30%** | Sampang (66.72), Bangkalan (67.70) |
+| `68 ≤ IPM < 72` | 1.15 | +15% | Sumenep, Probolinggo (kab), Bondowoso, Lumajang, Pamekasan, Pacitan, Pasuruan (kab), Situbondo, Jember, Madiun (kab) |
+| `72 ≤ IPM < 78` | 1.05 | +5% | Bojonegoro, Banyuwangi, Tulungagung, Malang (kab), Magetan, Gresik, Mojokerto (kab), Lamongan, Tuban, Ngawi, Kediri (kab), dll |
+| `IPM ≥ 78` | 1.00 | (no boost) | Sidoarjo, Kota Batu, Kota Surabaya, Kota Malang, Kota Kediri, Kota Madiun, dll |
+
+**Mengapa kalibrasi:** Threshold v9 lama (`<65 → 1.30`) tidak pernah ter-trigger karena IPM terendah Jatim 2024 = Sampang 66.72. v10 menggeser threshold sehingga klaim "+30% boost" demonstrably valid.
+
+**Catatan v11:** Boost +30% applies ke kab IPM <68 **saat menjadi deficit/penerima** (di-multiply dengan `base_score` dari Layer 2 untuk menghasilkan `final_score`). Demo run menunjukkan 2 dari 32 match trigger `EQUITY_BOOST_30` — keduanya Ngawi mengirim beras ke Madura (Bangkalan & Sampang). Saat Sampang sendiri jadi surplus (misal bawang), tidak ada boost karena bukan dia yang menjadi penerima. Honest framing: equity boost menggeser hasil saat low-IPM kab adalah sisi demand, bukan saat low-IPM kab disebutkan saja.
+
+**Update IPM tahunan:** Saat BPS publish IPM baru (biasanya BRS Desember), edit di [`sample_data/generate_sample_data.py:KABUPATEN_DATA`](sample_data/generate_sample_data.py) sebagai source of truth, lalu mirror ke [`data_sources/bps.py:IPM_2024_JATIM`](data_sources/bps.py).
+
+---
+
+## 24 Skenario Edge Case
+
+6 kategori, 24 skenario, semua tervalidasi pytest (bagian dari 205/205 total). Detail lengkap di [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) dan `AgriFlow_v11.docx` Section 5.5.5. **v11 menambahkan 5 commercial-reality scenarios** (C4 multi-holiday, D6 route blackout, E6 contract reserve, F1 grade substitution, F2 demand segmentation) di atas 19 skenario engineering edge case asli v10.
+
+### Kategori A — Volume (4 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| A1 | Surplus 1-to-many (1 surplus split ke beberapa deficit) | `TestA1_OneToMany` |
+| A2 | Many-to-1 (multiple surplus untuk 1 deficit besar) | `TestA2_ManyToOne` |
+| A3 | Volume mismatch drastis (<20% ratio → flag warning) | `TestA3_VolumeMismatchDrastis` |
+| A4 | Zero demand (suggest external opportunity) | `TestA4_ZeroDemand` |
+
+### Kategori B — Spasial (3 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| B1 | Cross-tier match (Tier 1 ↔ Tier 2) | `TestB1_CrossTier` |
+| B2 | Long distance (jarak > max_distance_km → REJECT) | `TestB2_LongDistance` |
+| B3 | Cluster Madura (4 kab semua surplus → ekspor) | `TestB3_ClusterMadura` |
+
+### Kategori C — Temporal (4 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| C1 | Ramadan/Idul Fitri spike (H-21 to H-1, RAMADAN_WEIGHTS) | `TestC1_RamadanSpike` |
+| C2 | Pasca panen raya (oversupply, multiple match) | `TestC2_PostHarvest` |
+| C3 | Stale data >24h (confidence drop bertingkat HIGH→MEDIUM→LOW) | `TestC3_StaleData` |
+| **C4** | **Multi-holiday calendar (Imlek H-7, Natal H-21, school-start H-14)** dengan weight profile per event | `TestC4_HolidayCalendar` |
+
+### Kategori D — Disrupsi (6 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| D1 | Banjir rute (BMKG hujan >50mm → climate_score 0.3) | `TestD1_BanjirRute` |
+| D2 | Komoditas hampir rusak (harvest age + transit > shelf) | `TestD2_KomoditasRusak` |
+| D3 | Harga anomali (>3σ dari rolling median → exclude) | `TestD3_HargaAnomali` |
+| D4 | Erupsi gunung (PVMBG MAGMA → UNREACHABLE) | `TestD4_ErupsiGunung` |
+| D5 | Banjir multi-kab (BNPB DIBI → emergency mode) | `TestD5_BanjirMultiKab` |
+| **D6** | **Route blackout (mudik H+1 Idul Fitri, demo Trans-Jawa, Suramadu maintenance)** dengan wildcard support | `TestD6_RouteBlackout` |
+
+### Kategori E — Politis & Kebijakan (6 skenario)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| E1 | Equity tie-break (IPM lebih rendah menang otomatis) | `TestE1_EquityTieBreak` |
+| E2 | Pemda override (`do_not_export_<komoditas>` flag) | `TestE2_PemdaOverride` |
+| E3 | Bulog priority (60% reserve, sisa 40% private) | `TestE3_BulogPriority` |
+| E4 | Import policy aktif (IMPORT_POLICY_WEIGHTS, price weight ↓) | `TestE4_ImportPolicy` |
+| E5 | BBM naik (max_distance shrink, logistics cost ↑) | `TestE5_BBMNaik` |
+| **E6** | **Contract reserve generalisasi (Carrefour MoU 70%, Indofood gula 50%, dll)** — Bulog pattern di-generalisir | `TestE6_ContractReserve` |
+
+### Kategori F — Kualitas & Segmentasi Komersial (2 skenario, NEW v11)
+
+| Kode | Skenario | Test |
+|---|---|---|
+| **F1** | **Grade substitution** — surplus `beras_premium` dapat memenuhi demand `beras_medium` (opt-in `allow_grade_substitution=True`); reverse direction tetap REJECT | `TestF1_GradeSubstitution` |
+| **F2** | **Demand segmentation** — `RETAIL` / `HORECA` / `GOVERNMENT` / `INDUSTRIAL` coexist untuk kab + komoditas yang sama; tiap segment di-match independen dengan flag `SEGMENT_<NAME>` | `TestF2_DemandSegmentation` |
+
+---
+
+## API Usage
+
+### Programmatic API
+
+```python
+from matching_engine import (
+    run_matching, SupplyNode, DemandNode,
+    Kabupaten, Tier, Commodity, LogisticsContext,
+)
+
+# Setup kabupaten (real koordinat & IPM 2024 BPS)
+kediri = Kabupaten(
+    id="3506", nama="Kediri",
+    latitude=-7.796, longitude=112.170,
+    ipm=74.50, tier=Tier.MEDIUM,
+)
+surabaya = Kabupaten(
+    id="3578", nama="Kota Surabaya",
+    latitude=-7.2575, longitude=112.7521,
+    ipm=84.69, tier=Tier.HIGH,
+)
+
+# Setup komoditas (constraint per komoditas)
+cabai = Commodity(
+    code="cabai_merah", nama="Cabai Merah Besar",
+    max_distance_km=200, min_viable_tons=1.0,
+    max_fresh_age_days=5,
+)
+
+# Run matching
+report = run_matching(
+    surplus_nodes=[
+        SupplyNode(kediri, cabai, volume_tons=80, price_per_kg=30000),
+    ],
+    deficit_nodes=[
+        DemandNode(surabaya, cabai, volume_tons=80, price_per_kg=60000),
+    ],
+    logistics=LogisticsContext(),
+)
+
+# Inspect hasil
+for m in report.matches:
+    print(f"{m.surplus.kabupaten.nama} → {m.deficit.kabupaten.nama}")
+    print(f"  Volume: {m.matched_volume_tons}t @ {m.distance_km:.0f}km")
+    print(f"  Score: {m.final_score:.1f} (base {m.base_score:.1f} × {m.equity_multiplier})")
+    print(f"  Confidence: {m.confidence.value}, Flags: {m.flags}")
+    # Realistic output dari demo Jatim:
+    #   Probolinggo → Kota Surabaya: 120.0t Bawang Merah
+    #   Score: 89.5 (base 89.5 × 1.00), Confidence: MEDIUM, Flags: []
+    #   Bangkalan → Gresik: 40.0t Bawang Merah
+    #   Score: 89.4 (base 85.1 × 1.05), Confidence: MEDIUM, Flags: ['EQUITY_BOOST_05', 'MADURA_CLUSTER']
+    #   Ngawi → Bangkalan: 250.0t Beras Premium
+    #   Score: 82.8 (base 63.7 × 1.30), Confidence: MEDIUM, Flags: ['EQUITY_BOOST_30', 'MADURA_CLUSTER']
+
+# Output:
+# Kediri → Kota Surabaya
+#   Volume: 80.0t @ 65km
+#   Score: 89.5 (base 89.5 × 1.0)
+#   Confidence: MEDIUM, Flags: []
+
+print(f"\nLatency: {report.run_metadata['latency_ms']}ms")
+print(f"Candidate pairs evaluated: {report.run_metadata['candidate_pairs_evaluated']}")
+print(f"Warnings: {len(report.warnings)}")
+```
+
+### Advanced — Skenario Override
+
+```python
+from matching_engine.constraints import set_bulog_procurement
+from datetime import datetime
+
+# Skenario E3: Bulog procurement aktif untuk Madiun
+set_bulog_procurement({"3519"})
+
+# Skenario E4: Import policy aktif (bobot price diturunkan)
+report = run_matching(
+    surplus_nodes=[...],
+    deficit_nodes=[...],
+    import_policy_active=True,  # IMPORT_POLICY_WEIGHTS
+)
+
+# Skenario C1: Force Ramadan mode untuk testing
+report = run_matching(
+    surplus_nodes=[...],
+    deficit_nodes=[...],
+    reference_date=datetime(2026, 3, 6),  # H-14 Idul Fitri 2026
+)
+
+# Skenario E5: BBM naik 20%
+from matching_engine.models import LogisticsContext
+report = run_matching(
+    surplus_nodes=[...],
+    deficit_nodes=[...],
+    logistics=LogisticsContext(
+        bbm_price_idr_per_liter=12000,
+        bbm_price_baseline=10000,
+    ),
+)
+```
+
+### Advanced — Force Algorithm Strategy
+
+```python
+# Force stable matching (Tier 1 algorithm)
+report = run_matching(..., force_strategy="stable")
+
+# Force greedy (Tier 2 algorithm) untuk testing
+report = run_matching(..., force_strategy="greedy")
+
+# Auto-detect (default): Tier 1↔Tier 1 pairs → stable, else → greedy
+report = run_matching(...)
+```
+
+---
+
+## Performance & Validation
+
+### Test Suite
+
+```bash
+$ pytest tests/ --tb=short
+============================= test session starts =============================
+collected 106 items
+
+tests/test_layer0_tier.py ................                           [ 15%]
+tests/test_layer1_constraints.py ...................                 [ 33%]
+tests/test_layer2_scoring.py .......................                 [ 54%]
+tests/test_layer3_allocation.py ..............                       [ 67%]
+tests/test_scenarios_disruption.py .........                         [ 76%]
+tests/test_scenarios_political.py ........                           [ 83%]
+tests/test_scenarios_spatial.py ......                               [ 89%]
+tests/test_scenarios_temporal.py .......                             [ 96%]
+tests/test_scenarios_volume.py ....                                  [100%]
+
+============================= 106 passed in 0.16s =============================
+```
+
+### Latency Benchmark
+
+```bash
+$ python benchmarks/latency.py
+```
+
+| Configuration | N (s × d) | p50 | p95 | p99 | Max |
+|---|---|---|---|---|---|
+| Sample data CSV (realistic) | 40 × 33 | 0.99 ms | 1.26 ms | 1.38 ms | 1.42 ms |
+| Synthetic full Jatim (38×19) | 361 × 361 | 48.37 ms | 53.67 ms | 55.53 ms | 58.43 ms |
+| Stress 100×100 (national scale) | 100 × 100 | 12.62 ms | 14.82 ms | 15.51 ms | 15.65 ms |
+| Stress 200×200 | 200 × 200 | 25.47 ms | 26.92 ms | 27.54 ms | 27.76 ms |
+
+**Verdict:** PASS — semua p99 < 500ms target. Highest p99 = 55.53ms (margin 88.9%).
+
+### National Scale (Indonesia 514 kab)
+
+⚠ **HONEST DISCLOSURE:** Engine v11 (sama dengan v10 — claim-precision pass, bukan engine change) saat ini BELUM siap untuk produksi nasional 514 kab. Lihat [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) Section 3.2 untuk detail. Optimization roadmap (spatial indexing, per-provinsi batching, parallel) sudah ter-quantify untuk Y2-Y3.
+
+```bash
+$ python benchmarks/national_scale.py
+```
+
+| Scale | Workload | p99 | vs target |
+|---|---|---|---|
+| Provinsi Jatim baseline | 333×389 | **14.2ms** | ✅ 35× under |
+| Multi-provinsi (100 kab) | 948×952 | **94.5ms** | ✅ 5× under |
+| Setengah Indonesia (250 kab) | 2326×2424 | **541.8ms** | ⚠ 1.08× over |
+| **Full Indonesia (514 kab)** | **4859×4907** | **2223.3ms** | ❌ **4.4× over** |
+
+---
+
+## Validasi Empiris Equity (Baseline Comparison)
+
+v12 menambah validasi kuantitatif klaim equity: membandingkan AgriFlow vs 4 strategi alternatif (pure-greedy, uniform, proportional-to-deficit, agriflow-smoothed) pada data Jatim yang sama, di dua rezim pasokan. Reproducible: `python benchmarks/equity_comparison_constrained.py` (output di `benchmarks/output/equity_comparison_constrained.md`).
+
+Metrik (volume-weighted): Coverage, Gini (Lorenz), Atkinson(ε=1), fulfillment Sampang (IPM 66.72) + Bangkalan (67.70).
+
+### Rezim A — pasokan MELIMPAH (surplus 8612t > defisit 5249t)
+
+| Strategi | Coverage | Gini | Atk(1.0) | Sampang | Bangkalan |
+|---|---|---|---|---|---|
+| pure_greedy | 0.890 | 0.093 | 0.113 | 1.00 | 1.00 |
+| **agriflow** | 0.880 | 0.099 | 0.114 | 1.00 | 1.00 |
+| uniform | 0.993 | 0.008 | 0.094 | 1.00 | 1.00 |
+| proportional | 0.993 | 0.007 | 0.094 | 1.00 | 1.00 |
+
+> **Jujur:** saat pasokan melimpah, equity nyaris tak terlihat — Sampang/Bangkalan sudah penuh terlayani di semua strategi, dan Gini AgriFlow (0.099) bahkan sedikit > greedy (0.093). Equity tidak punya panggung saat barang cukup untuk semua.
+
+### Rezim B — pasokan LANGKA (shock La Nina banjir Ngawi+Madiun+Bojonegoro, surplus 3962t < defisit 5249t, −32.5%)
+
+| Strategi | Coverage | Gini | Atk(1.0) | Sampang | Bangkalan |
+|---|---|---|---|---|---|
+| pure_greedy | 0.665 | 0.302 | 0.984 | **0.00** | **0.20** |
+| **agriflow** | 0.665 | 0.290 | 0.938 | **1.00** | **1.00** |
+| uniform | 0.627 | 0.252 | 0.186 | 1.00 | 1.00 |
+| proportional | 0.702 | 0.159 | 0.137 | 0.78 | 0.78 |
+
+> **Inti:** saat langka — ketika paling penting — greedy menelantarkan Sampang (0%) & Bangkalan (20%); **AgriFlow jamin keduanya 100% dengan biaya coverage agregat NOL** (0.665 = 0.665), Gini turun 0.302 → 0.290. Inilah nilai equity AgriFlow yang terukur. Klaim presisi: *"memprioritaskan kab terlemah saat pasokan langka"*, bukan *"menurunkan Gini secara umum"*.
+
+**Cliff tidak material:** `agriflow_smoothed` (linear-interp) ≈ step-function di kedua rezim; menggeser threshold IPM +1 poin hanya memindahkan 2 dari 38 kab antar tier.
+
+**Limitasi (roadmap v2):** alokasi binary di level demand-node (penuh/tidak), bukan proporsional → sensitivity threshold degenerate begitu kab terlindungi; belum ada provable bound (cf. Food Drop / Diaby 2024); equity multiplier masih heuristic post-score (cf. Firouz 2021).
+
+---
+
+## Data Sources
+
+8 connector dengan dual-mode (mock CSV + live API), graceful fallback:
+
+| Connector | Sumber | Frekuensi | Auth | Tier |
+|---|---|---|---|---|
+| [`pihps_bi.py`](data_sources/pihps_bi.py) | Bank Indonesia PIHPS | Harian (cut-off 13:00 WIB) | Tidak ada (scrape publik) | Tier 1 |
+| [`bapanas.py`](data_sources/bapanas.py) | Panel Harga Bapanas | Mingguan (Senin) | Tidak ada | Tier 2 |
+| [`bps.py`](data_sources/bps.py) | BPS WebAPI (IPM, produksi) | Tahunan (BRS Desember) | API key gratis | Both |
+| [`bmkg.py`](data_sources/bmkg.py) | BMKG / Open-Meteo (cuaca) | 3-6 jam refresh | Tidak ada (Open-Meteo) | Both |
+| [`pvmbg.py`](data_sources/pvmbg.py) | PVMBG MAGMA (gunung api) | Realtime saat status berubah | Tidak ada | Both |
+| [`bnpb.py`](data_sources/bnpb.py) | BNPB DIBI (bencana) | Realtime | Tidak ada | Both |
+| [`google_maps.py`](data_sources/google_maps.py) | Google Routes / OSRM fallback | Realtime per request | Google API key (paid) / OSRM gratis | Both |
+| [`hijri_calendar.py`](data_sources/hijri_calendar.py) | Aladhan API + hardcoded | Statis | Tidak ada | Both |
+
+### Fail-safe Strategy
+
+- Live API gagal → fallback ke mock CSV / hardcoded data
+- Weather data tidak tersedia → climate_score = 0.7 (neutral)
+- BPS API gagal → fallback ke `IPM_2024_JATIM` hardcoded
+- BMKG butuh adm4 mapping yang tidak ada → auto-fallback ke Open-Meteo
+- OSRM down → haversine geodesic + asumsi 60 km/h
+
+---
+
+## Project Structure
+
+```
+agriflow_engine/
+├── matching_engine/         # Core engine (5 modules, ~1000 lines)
+│   ├── __init__.py          # Public API
+│   ├── models.py            # Dataclasses (Kabupaten, Commodity, MatchResult, ...)
+│   ├── constraints.py       # Layer 0 + Layer 1 (9 hard constraints)
+│   ├── scoring.py           # Layer 2 (5-dim multi-objective scoring)
+│   ├── allocation.py        # Layer 3 (Gale-Shapley + Greedy + Equity)
+│   └── engine.py            # Main orchestrator + 19 skenario handlers
+├── data_sources/            # 8 connector dual-mode (mock + live)
+│   ├── pihps_bi.py          # Tier 1 PIHPS BI
+│   ├── bapanas.py           # Tier 2 Bapanas
+│   ├── bps.py               # IPM 2024 + produksi BPS
+│   ├── bmkg.py              # Cuaca BMKG/Open-Meteo
+│   ├── pvmbg.py             # Erupsi gunung PVMBG MAGMA
+│   ├── bnpb.py              # Bencana BNPB DIBI
+│   ├── google_maps.py       # Routing Google/OSRM
+│   └── hijri_calendar.py    # Ramadan/Idul Fitri Aladhan
+├── sample_data/             # CSV 38 kab × 19 komoditas Jatim
+│   ├── generate_sample_data.py  # Source of truth — regenerate CSV
+│   ├── loader.py                # CSV → engine objects
+│   ├── kabupaten_jatim.csv      # 38 kab + IPM 2024 + koordinat
+│   ├── komoditas_constraints.csv  # 19 komoditas + spec
+│   ├── surplus_deficit.csv      # 73 row sample workload
+│   ├── weather_forecast.csv     # 10 route forecast
+│   └── historical_price_stats.csv  # 19 commodity rolling stats
+├── tests/                   # 106 pytest test
+│   ├── conftest.py          # Fixtures (17 kab Jatim + factory)
+│   ├── test_layer0_tier.py             # 16 test (tier classification)
+│   ├── test_layer1_constraints.py      # 19 test (haversine + viability + Bulog)
+│   ├── test_layer2_scoring.py          # 23 test (5-dim scoring + weight schemes)
+│   ├── test_layer3_allocation.py       # 14 test (equity + stable + greedy)
+│   ├── test_scenarios_volume.py        # 4 test (A1-A4)
+│   ├── test_scenarios_spatial.py       # 6 test (B1-B3)
+│   ├── test_scenarios_temporal.py      # 7 test (C1-C3)
+│   ├── test_scenarios_disruption.py    # 9 test (D1-D5)
+│   └── test_scenarios_political.py     # 8 test (E1-E5)
+├── examples/
+│   └── run_demo.py          # End-to-end demo dengan output formatted
+├── benchmarks/
+│   ├── latency.py           # Multi-config provincial benchmark
+��   └── national_scale.py    # National scale stress test (514 kab)
+├── docs/
+│   ├── generate_v11_docx.py # Proposal v11 docx generator (claim-precision pass; current)
+│   ├── generate_v10_docx.py # Proposal v10 docx generator (history)
+│   └── AUDIT_v10.md         # Audit lengkap (consistency + national scale analysis)
+├── README.md                # This file
+├── requirements.txt         # Python dependencies
+└── venv/                    # (gitignored) virtual env
+```
+
+---
+
+## Development Guide
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/masterA88/agriflow_engine.git
+cd agriflow_engine
+python -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -r requirements.txt
+pip install python-docx  # untuk regenerate proposal docx
+```
+
+### Workflow
+
+1. **Edit code** di `matching_engine/` atau `data_sources/`
+2. **Run test** sebelum commit: `pytest tests/ -v`
+3. **Update sample data** kalau ubah threshold/komoditas: `python sample_data/generate_sample_data.py`
+4. **Run demo** untuk smoke test: `python examples/run_demo.py`
+5. **Run benchmark** kalau perubahan di hot path: `python benchmarks/latency.py`
+6. **Regenerate proposal** kalau perubahan di logic: `python docs/generate_v10_docx.py`
+
+### Add New Skenario
+
+1. Tambah test class di file yang sesuai (mis. `tests/test_scenarios_volume.py`)
+2. Tambah behavior di `matching_engine/engine.py` post-processing atau Layer yang relevan
+3. Update `AgriFlow_v10.docx` Section 5.5.5 (regenerate via `docs/generate_v10_docx.py`)
+4. Pastikan `pytest tests/ -v` masih PASS
+
+### Add New Komoditas
+
+1. Tambah row di [`sample_data/generate_sample_data.py:KOMODITAS_DATA`](sample_data/generate_sample_data.py)
+2. Tambah row di [`matching_engine/constraints.py:COMMODITY_SPECS`](matching_engine/constraints.py) (samakan max_distance/min_viable/max_fresh_age)
+3. Run `python sample_data/generate_sample_data.py` untuk regenerate CSV
+4. Update assertion di test kalau komoditas count check
+
+### Update IPM Tahunan (saat BPS publish data baru)
+
+1. Edit [`sample_data/generate_sample_data.py:KABUPATEN_DATA`](sample_data/generate_sample_data.py) (source of truth)
+2. Mirror ke [`data_sources/bps.py:IPM_2024_JATIM`](data_sources/bps.py)
+3. Run `python sample_data/generate_sample_data.py` untuk regenerate CSV
+4. Re-evaluate equity threshold di [`matching_engine/allocation.py:38`](matching_engine/allocation.py) — apakah masih meaningful trigger untuk distribusi baru?
+5. Run `pytest tests/ -v` — beberapa test mungkin perlu update kalau IPM bergeser
+
+---
+
+## Status & Roadmap
+
+### Current Status: ✅ Provincial-Ready (Jatim)
+
+- [x] 4-layer architecture implemented
+- [x] 19 skenario edge case handled
+- [x] 205/205 tests passing
+- [x] Latency p99 1.4ms (sample) - 55.5ms (stress)
+- [x] Equity multiplier kalibrasi BPS 2024 — Sampang & Bangkalan menerima +30% boost
+- [x] 8 data source connector dual-mode
+- [x] Cross-platform demo (Windows/Linux/Mac)
+- [x] Reproducible documentation generator
+
+### Roadmap to National Scale (Y2-Y3)
+
+⚠ **Honest disclosure:** Engine v11 (sama core dengan v10) saat ini BELUM siap untuk produksi nasional 514 kab. p99 untuk full Indonesia = 2.2 detik (4.4× over 500ms target).
+
+**Optimization plan** (lihat [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) Section 6):
+
+| Quick Win | Effort | Impact |
+|---|---|---|
+| Fix double-haversine bug di `generate_candidates` | 1 jam | 30-40% speedup Layer 1 |
+| Add geohash precision-5 spatial pre-filter | 1-2 hari | 25-50× speedup Layer 1 |
+| Multiprocessing per komoditas | 2-3 hari | Up to 19× speedup |
+| Distance matrix precompute (Redis cache) | 4 jam | 5-10× speedup |
+| Per-provinsi batching | 1 minggu | 5-15× speedup |
+
+**Combined estimate:** ~100-200× speedup → bring p99 dari 2200ms ke ~10-20ms untuk 514 kab nasional.
+
+### Data/Coverage Expansion (Y2)
+
+- [ ] `TIER_1_KOTA_IHK`: 8 kota Jatim → ~90 kota IHK Indonesia
+- [ ] `IPM_2024_JATIM` → `IPM_2024_INDONESIA` (514 kab/kota)
+- [ ] Cluster definitions: Madura → 10-20 cluster nasional
+- [ ] `GUNUNG_KABUPATEN_MAP`: 6 gunung Jatim → 130+ gunung api Indonesia
+- [ ] Sample data: 38 kab → 514 kab synthetic + real
+
+### Architectural Expansion (Y2-Y3)
+
+- [ ] Inter-island logistics (transport mode: truck/ferry/cargo plane)
+- [ ] Equity threshold recalibration nasional (range IPM 50-85)
+- [ ] CI/CD pipeline (GitHub Actions: pytest + benchmark assertions)
+- [ ] FastAPI wrapper untuk REST API production
+- [ ] Hybrid stable+greedy untuk skenario campuran tier
+- [ ] LLM integration (Gemini + Sahabat-AI Bahasa Daerah)
+
+---
+
+## Documentation
+
+| Document | Lokasi | Deskripsi |
+|---|---|---|
+| **Proposal v11** (current) | Generate via `python docs/generate_v11_docx.py` | Proposal lengkap dengan claim-precision pass — setiap klaim diferensiator dirujuk ke `file:line` di `matching_engine/` (docx gitignored — internal team artifact) |
+| **Proposal v10** (history) | Generate via `python docs/generate_v10_docx.py` | Versi sebelum claim-precision pass; tetap dipertahankan sebagai history |
+| **Audit v10** | [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md) | Consistency check + national scale analysis (engine code identik di v11) |
+| **README** | This file | Quick reference + getting started |
+| **Generator script** | [`docs/generate_v11_docx.py`](docs/generate_v11_docx.py) | Regenerate proposal v11 docx dari source |
+| **Code comments** | All `.py` files | Inline docstrings dengan reference ke proposal section |
+
+---
+
+## Troubleshooting
+
+### "ModuleNotFoundError: No module named 'matching_engine'"
+
+Make sure di project root saat run script:
+```bash
+cd agriflow_engine
+python examples/run_demo.py
+```
+
+Atau install sebagai package:
+```bash
+pip install -e .  # editable install (kalau pyproject.toml ada)
+```
+
+### Demo crash di Windows: "UnicodeEncodeError: 'charmap' codec"
+
+v10 sudah include UTF-8 fix. Pastikan pakai versi terbaru:
+```bash
+git pull
+```
+
+Atau set env variable manual:
+```bash
+set PYTHONIOENCODING=utf-8
+python examples/run_demo.py
+```
+
+### "FileNotFoundError: sample_data/kabupaten_jatim.csv"
+
+CSV belum di-generate. Run dulu:
+```bash
+python sample_data/generate_sample_data.py
+```
+
+### pytest collect 0 items
+
+Pastikan run dari project root, bukan dari `tests/`:
+```bash
+cd agriflow_engine  # not cd agriflow_engine/tests
+pytest tests/
+```
+
+---
+
+## License & Credits
+
+**Lisensi:** Hackathon submission. Code internal AgriFlow team.
+
+**Credits:**
+- **Algoritma:** Gale-Shapley sebagai operational primitive untuk centralized bipartite assignment dengan equity weighting (Gale & Shapley 1962; cf. Galichon 2021) — fires saat kedua kab Tier 1; Greedy multi-objective + equity priority untuk Tier 2 dan cross-tier
+- **Inspirasi platform:** eNAM (India), MealConnect (Feeding America), FEWS NET (USAID), Uber matching pattern, Food Drop Indiana
+- **Data sumber:** Bank Indonesia (PIHPS), Bapanas (Panel Harga), BPS (BRS Desember 2024 IPM), BMKG, PVMBG MAGMA, BNPB DIBI
+
+**Tim AgriFlow:** Hackathon DIGDAYA × PIDI 2026.
+
+**Citing:**
+```
+AgriFlow Team. (2026). AgriFlow Matching Engine v11.0:
+Purpose-Built Sub-National Indonesian Food Matching Engine
+dengan Stable Matching (Tier 1) + Greedy-Equity-Priority (Tier 2) + IPM-Based Equity Multiplier (BPS 2024).
+PIDI DIGDAYA × Hackathon 2026, Bank Indonesia.
+```
+
+---
+
+## Pertanyaan & Kontak
+
+- Issue tracker: GitHub Issues (this repo)
+- Proposal lengkap: regenerate via `python docs/generate_v10_docx.py` (output: `docs/AgriFlow_v10.docx`, gitignored)
+- Audit teknis: [`docs/AUDIT_v10.md`](docs/AUDIT_v10.md)
+
+**Deteksi. Prediksi. Distribusi. Untuk Semua.**
+*AgriFlow — Purpose-Built Sub-National AI Matching Engine for Indonesian Food Distribution.*

README_v13.md

@@ -0,0 +1,224 @@
+Language / Bahasa: [English](./README.en.md) · **Bahasa Indonesia**
+
+<p align="center"><img src="assets/logo-mark.png" alt="AgriFlow logo" width="300"/></p>
+
+<h1 align="center">AgriFlow</h1>
+
+<p align="center">
+  <strong>AI-Powered Food Security Intelligence Platform</strong><br/>
+  <em>Platform Matching Demand–Supply Pangan Antarwilayah</em>
+</p>
+
+<p align="center"><b>Deteksi · Prediksi · Distribusi</b></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/PIDI-DIGDAYA%20%C3%97%20Hackathon%202026-1B5E20?style=for-the-badge" alt="Hackathon"/>
+  <img src="https://img.shields.io/badge/Problem%20Statement-2%20Matching%20Demand–Supply-4CAF50?style=for-the-badge" alt="PS"/>
+  <img src="https://img.shields.io/badge/tests-520%20passing-brightgreen?style=for-the-badge" alt="Tests"/>
+</p>
+
+> **Roadmap proyek dibagi 3 Phase.** README teknis lengkap versi sebelumnya diarsipkan di [`README_v12.md`](README_v12.md) dan [`README_v11.md`](README_v11.md).
+
+---
+
+<details>
+<summary><b>🖼️ Lihat Research Poster (klik untuk expand)</b></summary>
+
+<br/>
+
+<p align="center"><img src="poster/agriflow-poster.jpg" alt="AgriFlow Research Poster" width="100%"/></p>
+
+</details>
+
+---
+
+# 📍 Phase 1 — Tim & Tautan
+
+## Tim
+
+| Nama | Role | LinkedIn |
+|------|------|----------|
+| Chelsea | Data Analyst | [Chelsea](https://linkedin.com/in/chelseaayu) |
+| Hilmi | Data Architect | [Hilmi](https://linkedin.com/in/hilmi888/) |
+| Monika | UX Researcher | [Monika](https://linkedin.com/in/monika-hermiani) |
+| Irpan | Data Engineer | [Irpan](https://linkedin.com/in/irpanpilihanrambe) |
+
+## Tautan
+
+| Resource | Link |
+|----------|------|
+| Pitch Deck | [Canva](https://www.canva.com/design/DAHETj2ulzg/VIvgxVkQ6I9R24ucphy2mQ/view) |
+| Dashboard (Live Demo) | [agriflow-engine.vercel.app](https://agriflow-engine.vercel.app/) |
+| Proposal (v13) | [docs/AgriFlow_Proposal_v13.pdf](docs/AgriFlow_Proposal_v13.pdf) |
+
+---
+
+# 🚀 Phase 2 — Yang Sudah Kami Bangun (MVP)
+
+## Masalah
+
+Setiap tahun Indonesia kehilangan triliunan rupiah pangan — **40% terjadi di distribusi, bukan produksi**. Di satu kabupaten petani membuang cabai karena harga jatuh; di kabupaten sebelah harga melonjak karena langka. Pemda sering baru tahu krisis **2–3 minggu kemudian**.
+
+## Solusi
+
+**AgriFlow mencocokkan kabupaten surplus dengan kabupaten defisit** — seperti "Uber untuk pangan", tapi paham masa simpan (perishability), jarak jalan nyata, dan **keadilan untuk daerah tertinggal**. Tiga fungsi inti:
+
+- **Deteksi** — temukan anomali harga (lonjakan/anjlok) dari data harga harian.
+- **Prediksi** — perkirakan harga 30 hari ke depan.
+- **Distribusi** — cocokkan surplus → defisit secara cerdas & adil.
+
+## Arsitektur (High-Level)
+
+```
+   SUMBER DATA NYATA                AGRIFLOW ENGINE                  AKSES
+  (BPS · PIHPS · OSRM)        ┌──────────────────────────┐
+  produksi · konsumsi ──────▶ │ DETEKSI    anomali harga  │ ──┐
+  harga · populasi            │ PREDIKSI   forecast 30 hr │   ├──▶ Dashboard peta
+  per-kabupaten Jatim         │ DISTRIBUSI matching 4-lapis│  └──▶ WhatsApp bot
+                              └──────────────────────────┘
+```
+
+Tiga fungsi (Deteksi · Prediksi · Distribusi) berbagi satu sumber data nyata, lalu disajikan lewat Dashboard & WhatsApp.
+
+📄 **Detail metodologi tiap fitur — alasan pemilihan metode, cara kerja, evaluasi, validasi, dan sitasi paper: [Dokumen Arsitektur (PDF)](docs/AgriFlow_Architecture.pdf).**
+
+## Fitur yang sudah berjalan
+
+| Fungsi | Fitur | Status |
+|--------|-------|:------:|
+| **Distribusi** | Matching engine 4-lapis (hard constraints → multi-objective scoring → equity) berjalan di **data BPS asli per-kabupaten (2022)** | ✅ |
+| **Deteksi** | Deteksi anomali harga (deseasonalize + robust statistics) pada harga PIHPS harian **2021–2025** | ✅ |
+| **Prediksi** | Forecasting harga 30 hari dengan **TimesFM 2.0** (foundation model time-series) | ✅ |
+| **Aksesibilitas** | **Chatbot WhatsApp** (tanya harga & rekomendasi) + **Dashboard** peta interaktif | ✅ |
+| **Keamanan** | Sistem akun Supabase (JWT terverifikasi server-side, Row Level Security di 12 tabel, reset password) siap untuk model berlangganan; peta & fitur inti tetap **terbuka publik** (`REQUIRE_AUTH=false`) selama periode penjurian | ✅ |
+| **Data nyata** | **6 komoditas** real per-kab: beras premium & medium, cabai merah & rawit, bawang merah & putih + harga PIHPS 5 tahun | ✅ |
+
+> **Kualitas:** 520 tes otomatis lulus (521 terkumpul, 1 di-skip) — engine teruji, dapat direproduksi, dan jujur soal keterbatasannya (lihat [Pengujian & Skenario](#pengujian--skenario) dan Phase 3).
+
+### Cuplikan
+
+**Dashboard** — peta Jawa Timur dengan bubble surplus/defisit per kabupaten, daftar *top matches*, plus panel **Forecast & Anomali harga** (ketiga fungsi dalam satu layar):
+
+![Dashboard AgriFlow](assets/dashboard.png)
+
+**WhatsApp Bot** — tanya harga, cari pembeli/pemasok, prediksi & anomali harga lewat chat. Mendukung **Bahasa Indonesia** dan **Bahasa Jawa** (inklusi petani daerah):
+
+| Bahasa Indonesia | Bahasa Jawa |
+|:---:|:---:|
+| ![WhatsApp Bahasa Indonesia](assets/whatsapp-id.png) | ![WhatsApp Bahasa Jawa](assets/whatsapp-jawa.png) |
+
+## Pengujian & Skenario
+
+Karena output AgriFlow menggerakkan alokasi pangan antar-kabupaten yang menyentuh daerah IPM-rendah, klaim "adil" dan "robust" harus dapat diaudit ulang — bukan sekadar narasi. Suite uji mengunci angka food-balance sebagai *golden numbers* (reproducibility), menjaga parameter kebijakan dari pergeseran tak sengaja (regression-safety), dan menguji deteksi anomali secara adversarial.
+
+**521 tes terkumpul · 520 lulus · 1 di-skip · lintas-OS di CI.**
+(Skip = `test_timesfm_importorskip`: dilewati jika pustaka TimesFM tak terpasang di runner; jalur forecasting tetap diuji via fallback + kontrak API.)
+
+Server produksi memuat **data BPS asli secara default** (`DATA_BACKEND=csv`, bawaan). Fixture sintetis 19-komoditas lama tetap dipakai di 13 file test (`DATA_BACKEND=demo`) untuk menguji logika engine di lebih banyak variasi komoditas — tidak pernah disajikan ke pengguna.
+
+| Kategori | Jumlah | Cakupan |
+|---|---|---|
+| Unit per-layer (L0–L3) | 73 | Tier IPM, constraint jarak/perishability, skor, alokasi equity |
+| 24 skenario edge-case (A–F) | 27+ | Volume, spasial, temporal, disrupsi, politis, kualitas |
+| Validasi data nyata BPS/PIHPS | 57 | Food-balance beras + hortikultura 2022, pipeline reproducible |
+| Deteksi anomali harga | 49 | S-H-ESD sadar-musiman pada residual deseasonalized |
+| Forecast & API | 40 | Endpoint forecast/anomali + fallback |
+| Baseline & equity | 39 | greedy/uniform/proporsional vs AgriFlow + skenario langka pasokan |
+| Ingest & integrasi | 73 | DB loader, ingest PIHPS, jarak OSRM, bot WhatsApp |
+| Autentikasi dashboard & kuota WhatsApp | 117 | Login Supabase, verifikasi JWT server-side, RLS 12 tabel, reset password, kuota gratis WhatsApp (nonaktif default) |
+
+**24 skenario edge-case** memetakan kejadian nyata Jawa Timur, contohnya: Ramadan spike (C1), erupsi Semeru di Lumajang → unreachable (D4), banjir multi-kabupaten sentra padi (D5), kenaikan BBM → biaya logistik naik (E5), dan prioritas reserve kontrak Bulog (E3).
+
+**Hasil kunci:**
+- **Equity terbukti saat pasokan langka, biaya efisiensi nol.** *Ini uji-tekan hipotetis, bukan hasil data BPS asli:* Jawa Timur pada data 2022 justru sangat surplus (rasio 6,6×), sehingga nilai equity tidak akan tampak. Untuk menunjukkan cara kerja mekanismenya kami membangun skenario langka buatan (fixture `surplus_deficit_constrained.csv`, surplus 3962t vs defisit 5249t). Di skenario itu greedy murni menelantarkan Madura — Sampang **0%**, Bangkalan **20%**; AgriFlow mengangkat keduanya ke **100%** dengan *coverage agregat identik* (0.6649) dan Gini turun (0.3017 → 0.2905). Kami tidak mengklaim keunggulan equity saat pasokan melimpah, dan tidak mengklaim skenario ini berasal dari data nyata.
+- **Anomali sadar-musiman.** Penurunan harga ~60% ter-flag, tapi pola musiman murni (siklus jelang Lebaran) **tidak** memicu false positive; anomali genuine di atas pola musiman tetap terdeteksi.
+- **Data mengungkap defisit struktural, bukan bug.** Bawang putih menghasilkan **0 match** di seluruh 38 kabupaten pada data BPS 2022 — Jawa Timur defisit bawang putih di semua kabupaten, konsisten dengan Indonesia sebagai net-importir bawang putih. Engine bekerja benar; datanya yang bicara.
+
+📄 Detail lengkap (kenapa, daftar 24 skenario, sitasi paper): [Dokumen Arsitektur](docs/AgriFlow_Architecture.pdf) §Pengujian & Validasi.
+
+## Kenapa tech stack kami RINGKAS (bukan sebanyak proposal awal)?
+
+Proposal awal mencantumkan stack besar (Qdrant, LangChain, Redis, n8n, multi-cloud, dll). Setelah benar-benar membangun, kami **sengaja memangkasnya** — *honest engineering* untuk skala saat ini (38 kabupaten Jawa Timur):
+
+| Rencana awal | Yang kami pakai | Alasan |
+|---|---|---|
+| Qdrant (vector DB terpisah) | **Supabase pgvector** | Korpus kecil — tak perlu service vektor sendiri |
+| LangChain | **Gemini API langsung** | RAG sesederhana ini tak butuh framework berat |
+| Redis cache | **In-process cache** | Beban belum menuntut; engine deterministik |
+| 5 platform hosting | **2 (HF Spaces + Vercel)** | Lebih sedikit titik gagal, lebih murah |
+
+**Prinsip kami: pakai yang cukup, bukan yang ramai.** Komponen besar baru bernilai saat skala membenarkannya — dan itulah **Phase 3**.
+
+## 🎙️ Validasi Lapangan — Wawancara Petani
+
+Kami mewawancarai **4 petani lintas komoditas & skala usaha** — dari petani mapan dengan jaringan pasar sampai petani kecil yang terkurung tengkulak — untuk memvalidasi kebutuhan nyata dan menemukan gap AgriFlow. Tiap baris menyertakan **rekaman audio sebagai bukti**.
+
+| Komoditas | Profil Narasumber | Pendapat Singkat | Rekaman & Transkrip |
+|---|---|---|---|
+| **Bawang Merah** | Denisa Septalian ��� petani penerus, Nganjuk (Ds. Ngudikan, Kec. Wilangan), 5 thn, lahan ±70 ru | **Setuju bersyarat.** Info harga saja "kurang efektif" karena 100% bergantung tengkulak & tak punya akses luar daerah — antusias bila AgriFlow membuka **akses pembeli luar kota**. | [🎧 Audio](https://drive.google.com/drive/folders/1kdF9KPqycrdN9GewRz6YKFUKWfzCaRVh) · [📄 Transkrip](interview/transcript-bawang-merah.md) |
+| **Padi** | Petani 15 thn, lahan ±1 ha; jual gabah ~Rp5.800/kg ke tengkulak yang datang ke sawah | Info harga lintas daerah **membantu** sebagai gambaran; tertarik pembeli luar kota asal prosesnya aman; ragu "ribet" di awal & soal keamanan transaksi. | [🎧 Audio](https://drive.google.com/drive/folders/1-fpMk8UGg41wk1-RZufTyRBNNJwM7he7) · [📄 Transkrip](interview/transcript-padi.md) |
+| **Cabai** | Petani baru (8 bln bertani, tanaman 50 HST), Solo/Karanganyar; sebelumnya jagung | **Sangat tertarik** harga real-time antar daerah untuk hitung kelayakan kirim; info FB/WA kini meleset Rp5.000–15.000/kg & hanya level provinsi. Menekankan UI sederhana untuk petani lansia. | [🎧 Audio](https://drive.google.com/drive/folders/1lStLTY4L_9NW-UXAWrfTXwNc0CuiUQT-) · [📄 Transkrip](interview/transcript-cabai.md) |
+| **Kentang** | Labib — Dieng, Banjarnegara, ±6 ha, 2 thn; jual ke Pasar Induk Kramat Jati | Info antar daerah berguna sebagai **pembanding & referensi keputusan**, tetap utamakan pedagang langganan. Kunci keberhasilan: **akurasi data + sumber jelas + update real-time**. | [🎧 Audio](https://drive.google.com/drive/folders/1mMVWLv6uQQzlD_KNrkI5eSARXHTlDK9K) · [📄 Transkrip](interview/transcript-kentang.md) |
+
+### Analisis & Kesimpulan — Nilai Plus AgriFlow yang Tervalidasi
+
+- **Masalah inti tervalidasi lintas komoditas.** Keempat petani menyebut keluhan yang sama: harga tidak stabil, panen raya serentak → harga anjlok, dan **butaan informasi harga antar daerah** — persis yang dijawab fungsi **Deteksi + Prediksi**.
+- **WhatsApp sebagai kanal — tervalidasi 4/4.** Semua memilih WhatsApp (bisa dibaca ulang, sudah dipakai semua petani) di atas SMS/aplikasi baru → memperkuat keputusan **WhatsApp bot**.
+- **Matching surplus→defisit menjawab keluhan paling tajam.** "Tidak ada akses keluar daerah" (bawang merah, padi) adalah problem yang langsung diselesaikan **matching engine 4-lapis**; begitu ditawari pembeli luar kota berharga lebih baik, **keempatnya tertarik**.
+- **Prediksi harga punya nilai konkret.** Semua pernah "kesusu" / salah memperkirakan harga (bawang merah sempat jual Rp10.000, dua hari kemudian Rp20.000) → **forecast 30 hari** menjawab kebutuhan ini.
+- **Kesediaan membayar ada** — bersyarat manfaat ekonomi terbukti & data akurat. Tak satu pun menolak model berbayar.
+
+> Temuan **gap fitur** dari wawancara (akses transaksi, granularitas harga, transparansi & keamanan) kami petakan secara jujur ke **Phase 3** di bawah.
+
+---
+
+# 🌐 Phase 3 — Rencana Lanjutan & Scaling
+
+Komponen di bawah ini **sengaja kami tunda** karena *over-engineering* untuk skala sekarang. Kami kerjakan saat **scaling up**:
+
+| Rencana Phase 3 | Untuk apa |
+|---|---|
+| **Skala nasional 514 kab** | Dari 38 kab Jatim → seluruh Indonesia (perlu spatial partitioning + precompute jarak) |
+| **Exogenous forecasting** (indeks ENSO/iklim, kalender Ramadan) | Akurasi prediksi naik saat ada guncangan iklim & hari raya |
+| **Qdrant / Redis / n8n** | Vector scale, caching, orkestrasi terjadwal — saat beban nyata muncul |
+| **Sahabat-AI (Bahasa Jawa/Madura) + IVR telepon** | Inklusi petani lansia & pengguna feature-phone |
+| **Daging ayam & telur (data real)** | Perlu data produksi broiler & telur-ras per-kab yang lengkap |
+| **Fasilitasi transaksi / akses pasar luar daerah** *(gap dari wawancara)* | Temuan bawang merah & padi: info harga saja "kurang efektif" tanpa saluran jual-beli yang memutus ketergantungan tengkulak |
+| **Harga granular per kota/pasar** *(gap dari wawancara)* | Temuan cabai: sumber kini hanya level provinsi; selisih harga riil bisa Rp5.000–15.000/kg |
+| **Transparansi sumber data & jaminan keamanan transaksi** *(gap dari wawancara)* | Syarat kepercayaan: Labib menanyakan sumber & mekanisme update; padi ragu keamanan transaksi + petani lansia butuh onboarding anti-"ribet" |
+
+## Cakupan saat ini (yang membatasi adalah ketersediaan data, bukan sistem)
+
+Mesin AgriFlow **sudah siap memproses data apa pun yang diberikan**. Cakupan sekarang ditentukan oleh **ketersediaan data publik per-kabupaten** — begitu sumber datanya terbuka, pipeline yang sama langsung memprosesnya tanpa ubah arsitektur.
+
+| Cakupan sekarang | Gerbangnya: ketersediaan data |
+|---|---|
+| 6 komoditas inti | Engine menerima komoditas apa pun; sisanya menunggu data **produksi per-kabupaten** dirilis BPS pada granularitas sama |
+| Tahun acuan 2022 | Tahun konsisten terbaru yang lengkap di semua sumber per-kab; tahun lebih baru tinggal di-*ingest* saat BPS merilis |
+| Daging ayam & telur belum | Data produksi broiler/ayam-ras per-kab belum tersedia di sumber publik; 13 komoditas lain (termasuk telur & daging ayam) masih berstatus **placeholder sintetis** di `historical_price_stats.csv`, tidak terjangkau lewat backend produksi (`DATA_BACKEND=csv`) |
+| Konsumsi cabai/bawang via angka nasional | Konsumsi *per-kabupaten* untuk komoditas ini belum dipublikasikan; konsumsi **beras sudah per-kab & dipakai nyata** |
+| Harga Tier-2 (kab non-IHK) | Panel Harga Bapanas sedang pemeliharaan; saat feed pulih, 30+ kab tambahan langsung tercakup |
+
+## Scaling up
+
+Peningkatan skala (nasional 514 kab, multi-komoditas penuh, real-time) **dibatasi oleh laju keterbukaan data publik per-kabupaten — bukan oleh kesiapan teknis.** Engine sudah siap; tinggal data feed-nya tersedia, lalu optimasi skala (spatial partitioning). Pendekatan kami: **buktikan nilai dulu di skala provinsi dengan data nyata, lalu perluas seiring data tersedia.** Foundation-model forecasting (TimesFM 2.0) dan kanal suara/Bahasa daerah adalah peningkatan terjadwal fase berikutnya.
+
+---
+
+## Menjalankan (teknis singkat)
+
+```bash
+pip install -r requirements.txt
+python examples/run_demo_real.py   # demo matching pada data BPS asli 2022
+pytest tests/                      # 520 lulus, 1 di-skip
+```
+
+Detail engineering lengkap ada di [`README_v12.md`](README_v12.md).
+
+---
+
+## Lisensi
+
+MIT License — &copy; 2026 Hilmi. Lihat [`LICENSE`](LICENSE).
+
+<p align="center"><em>Deteksi · Prediksi · Distribusi — untuk ketahanan pangan Indonesia.</em></p>

REAL_DATA_METHODOLOGY.md

@@ -0,0 +1,194 @@
+# Real Data Methodology — Surplus/Deficit 2022
+
+## Status per commodity
+
+| Commodity | Status | Source | Tahun |
+|---|---|---|---|
+| `beras_premium` | REAL (derived) | BPS per-kab produksi + konsumsi + populasi | 2022 |
+| `beras_medium` | REAL (derived, grade-split assumption 60/40) | same | 2022 |
+| `cabai_merah` | REAL produksi (BPS Hortikultura); konsumsi proxy nasional (Kementan) | BPS Jatim Hortikul. + Kementan PDF | 2022 |
+| `cabai_rawit` | REAL produksi (BPS Hortikultura); konsumsi proxy nasional (Kementan) | same | 2022 |
+| `bawang_merah` | REAL produksi (BPS Hortikultura); konsumsi proxy nasional (Kementan) | same | 2022 |
+| `bawang_putih` | REAL produksi (BPS Hortikultura); konsumsi proxy nasional (Kementan) | same | 2022 |
+| `daging_ayam` | EXCLUDED — data tidak lengkap (broiler hilang; ayam petelur 2 kab) | — | PENDING |
+| `telur_ayam` | EXCLUDED — telur petelur hanya 2 kab | — | PENDING |
+
+---
+
+## Reference year: 2022
+
+All three beras inputs AND semua 5 hortikultura source files have 2022 data.
+**2022** is selected as the reference year because:
+- Beras: 2022 is the latest year where produksi, konsumsi per-kab, AND populasi are all
+  present and plausible for all 38 kab/kota. (2025 populasi corrupted ~1000x.)
+- Hortikultura: BPS Hortikultura files have `Produksi_2021` and `Produksi_2022` columns;
+  2022 is the most recent available year.
+- Konsumsi per-kapita hortikultura: Kementan Statistik Konsumsi Pangan 2024 provides
+  2022 values in Tabel 4.6a (cabai) and 4.1a/4.2a (bawang).
+
+---
+
+## Data sources
+
+### Beras (all BPS-grade, per-kabupaten)
+
+| Dataset | File | Source | Unit |
+|---|---|---|---|
+| Produksi beras | `sample_data/bps_real/year_beras.csv` | BPS Jawa Timur | ton/tahun/kab |
+| Konsumsi per kapita | `sample_data/bps_real/week_konsumsi_beras_perkapita.csv` | BPS Indonesia (Susenas) | kg/kapita/minggu |
+| Populasi | `sample_data/bps_real/year_populasi_jatim.csv` | BPS Jawa Timur | jiwa |
+
+### Hortikultura
+
+| Dataset | File | Source | Unit | Konversi |
+|---|---|---|---|---|
+| Produksi cabai besar | `bps_real/cabai_besar.csv` | BPS Jatim Hortikul. | **KUINTAL**/tahun | ÷10 = ton |
+| Produksi cabai keriting | `bps_real/cabai_keriting.csv` | same | KUINTAL/tahun | ÷10 = ton |
+| Produksi cabai rawit | `bps_real/cabai_rawit.csv` | same | KUINTAL/tahun | ÷10 = ton |
+| Produksi bawang merah | `bps_real/bawang_merah.csv` | same | KUINTAL/tahun | ÷10 = ton |
+| Produksi bawang putih | `bps_real/bawang_putih.csv` | same | KUINTAL/tahun | ÷10 = ton |
+
+**Satuan konfirmasi**: Total row cabai_besar 2022 = 851,445 kuintal = 85,145 ton → sesuai
+BPS published figure Jatim. Konversi ÷10 (kuintal → ton) terverifikasi.
+
+### Konsumsi per kapita hortikultura — NATIONAL PROXY (Kementan)
+
+Sumber: **Statistik Konsumsi Pangan 2024**, Pusat Data dan Sistem Informasi Pertanian,
+Kementerian Pertanian. Desember 2024.
+URL: https://satudata.pertanian.go.id/assets/docs/publikasi/Buku_Statistik_Konsumsi_2024.pdf
+
+| Komoditas | Tabel | Hal. | Nilai 2022 | Catatan |
+|---|---|---|---|---|
+| Cabai merah | 4.6a (Cabe merah/Chillies) | 30 | **1.909 kg/kapita/tahun** | Susenas per-kapita nasional |
+| Cabai rawit | 4.6a (Cabe rawit/Cayenne pepper) | 30 | **2.073 kg/kapita/tahun** | same |
+| Bawang merah | 4.1a (Bawang merah/Onion) | 25 | **3.024 kg/kapita/tahun** | same |
+| Bawang putih | 4.2a (Bawang putih/Garlic) | 26 | **2.016 kg/kapita/tahun** | same |
+
+**PROXY WARNING**: Angka ini adalah RATA-RATA NASIONAL dari Susenas. Tidak ada data konsumsi
+per-kabupaten untuk hortikultura. Konsumsi aktual per kab bisa berbeda dari angka nasional
+(terutama kota besar vs pedesaan, atau daerah produsen di mana konsumsi lokal bisa lebih tinggi).
+Hasil surplus/deficit hortikultura harus dibaca dengan caveat ini.
+
+---
+
+## Derivation formula
+
+### Beras
+
+```
+konsumsi_ton = avg_konsumsi_perkapita_kg_per_minggu × 52 × populasi / 1000
+net_ton      = produksi_ton − konsumsi_ton
+role         = "SURPLUS" if net_ton > 0 else "DEFICIT"
+volume_tons  = abs(net_ton)
+```
+
+Per-kab BPS Susenas data digunakan untuk konsumsi beras (bukan proxy nasional).
+
+### Hortikultura (cabai merah, cabai rawit, bawang merah, bawang putih)
+
+```
+produksi_ton  = (Produksi_2022 kuintal) / 10         # BPS file, kuintal -> ton
+konsumsi_ton  = perkapita_kg_per_tahun × populasi_2022 / 1000  # Kementan national avg
+net_ton       = produksi_ton − konsumsi_ton
+role          = "SURPLUS" if net_ton > 0 else "DEFICIT"
+volume_tons   = abs(net_ton)
+```
+
+Cabai merah = cabai_besar + cabai_keriting (dijumlahkan sebelum derivasi).
+
+---
+
+## Grade split beras: ASSUMPTION
+
+60% net beras → `beras_premium`; 40% → `beras_medium`. Working assumption.
+
+---
+
+## Harga (2022 PIHPS median dari sample_data/price_history/)
+
+| Komoditas | Harga IDR/kg | Sumber |
+|---|---|---|
+| `beras_premium` | 11,500 | median(super1=12,000; super2=11,000) PIHPS 2022 |
+| `beras_medium` | 10,325 | median(medium1=10,650; medium2=10,000) PIHPS 2022 |
+| `cabai_rawit` | 41,000 | cabe_rawit_cleaned.csv 2022 median, PIHPS |
+| `bawang_merah` | 32,500 | bawang_merah_cleaned.csv 2022 median, PIHPS |
+| `bawang_putih` | 20,750 | bawang_putih_cleaned.csv 2022 median, PIHPS |
+| `cabai_merah` | 45,000 | **FLAGGED: komoditas_constraints.csv baseline** — cabai merah tidak ada di PIHPS dataset |
+
+---
+
+## harvest_age_days
+
+| Role | Value | Rationale |
+|---|---|---|
+| SURPLUS | 28 | Typical post-harvest/milling age when komoditas leaves origin kab (conservative estimate) |
+| DEFICIT | 0 | Convention: deficit nodes are demand points; age irrelevant |
+
+---
+
+## Name-to-kab_id mapping
+
+**Beras source files**: menggunakan nama BPS full ("Kabupaten X" / "Kota X") →
+strip prefix untuk match ke `kabupaten_jatim.csv` short name.
+
+**Hortikultura source files**: menggunakan nama pendek tanpa prefix positional:
+- Baris 0-28 (29 baris): Kabupaten, urutan kode BPS 3501 (Pacitan) s/d 3529 (Sumenep)
+- Baris 29-37 (9 baris): Kota, urutan kode BPS 3571 (Kota Kediri) s/d 3579 (Kota Batu)
+- Baris 38: "Total" — EXCLUDED
+
+Semua 38 kab/kota Jatim ter-map tanpa exception untuk tahun 2022.
+
+---
+
+## Sanity check results (2022)
+
+### Beras — top surplus kabupaten
+
+| kab_id | Kabupaten | Net beras (ton) | Role |
+|---|---|---|---|
+| 3524 | Kab. Lamongan | +409,023 | SURPLUS |
+| 3521 | Kab. Ngawi | +366,367 | SURPLUS |
+| 3522 | Kab. Bojonegoro | +295,679 | SURPLUS |
+| 3523 | Kab. Tuban | +184,507 | SURPLUS |
+| 3519 | Kab. Madiun | +195,419 | SURPLUS |
+
+### Cabai merah — top surplus
+
+| kab_id | Kabupaten | Surplus (ton) |
+|---|---|---|
+| 3507 | Kab. Malang | ~22,328 |
+| 3513 | Kab. Probolinggo | ~9,823 |
+| 3510 | Kab. Banyuwangi | ~7,177 |
+
+### Cabai rawit — top surplus
+
+| kab_id | Kabupaten | Surplus (ton) |
+|---|---|---|
+| 3510 | Kab. Banyuwangi | ~100,709 |
+| 3507 | Kab. Malang | ~81,866 |
+| 3506 | Kab. Kediri | ~77,761 |
+
+### Bawang merah — top surplus
+
+| kab_id | Kabupaten | Surplus (ton) |
+|---|---|---|
+| 3518 | Kab. Nganjuk | ~190,610 |
+| 3513 | Kab. Probolinggo | ~54,731 |
+| 3507 | Kab. Malang | ~43,099 |
+
+### Bawang putih
+
+Seluruh 38 kab/kota DEFICIT. Jatim total produksi ~855 ton vs kebutuhan ~80,000+ ton.
+(Jatim bukan produsen bawang putih; pasokan dari Temanggung/Brebes Jateng dan impor.)
+
+Semua hasil ini sesuai ekspektasi geografis.
+
+---
+
+## Excluded
+
+- **Daging ayam**: Data folder download berisi `daging_ayam_kampung.csv` dan
+  `daging_ayam_petelur.csv`. Broiler (sumber utama produksi komersial) tidak ada.
+  Data tidak representatif untuk routing engine. **Status: PENDING.**
+- **Telur ayam**: `telur_ayam_petelur.csv` hanya 2 kabupaten ter-cover.
+  **Status: PENDING.**

analysis/__init__.py

@@ -0,0 +1,8 @@
+"""
+analysis/ — Price anomaly detection and statistical analysis for AgriFlow.
+
+This package is intentionally dependency-light: numpy + stdlib csv only.
+No pandas, no statsmodels, no sklearn.  Results are interpretable by
+construction — every flagged point shows the rolling median it deviated from
+and the exact percentage deviation.
+"""

analysis/forecast_timesfm.py

@@ -0,0 +1,309 @@
+"""
+analysis/forecast_timesfm.py  --  Offline forecast precompute for AgriFlow.
+
+ARCHITECTURE:
+    This script runs OFFLINE (locally, not on HF Space) because TimesFM ~2GB
+    model cannot be loaded on the free-tier Space (OOM).  The output JSON files
+    are committed to the repo and the backend serves them at runtime without
+    importing this module or timesfm.
+
+HONESTY POLICY:
+    If TimesFM cannot be loaded (not installed, network unavailable, Python
+    version incompatible), this script falls back to a seasonal-naive baseline
+    that is CLEARLY labelled in the output as "method": "seasonal_naive_baseline"
+    so consumers can distinguish it from a genuine TimesFM forecast.
+
+    DO NOT change the labelling.  If you want TimesFM output, fix the environment
+    and re-run.
+
+TIMESFM STATUS (2026-05-31):
+    timesfm PyPI package (1.0.0) requires Python <=3.11 + jaxlib==0.4.26.
+    This project runs Python 3.12+.  TimesFM 2.0 (PyTorch variant) is on
+    HuggingFace Hub but requires the same pinned JAX+Flax stack via the PyPI
+    package.  Install blocker is hard on Python 3.12/3.14.
+
+    To use real TimesFM:
+      1. Run this script with Python 3.11: `py -3.11 analysis/forecast_timesfm.py`
+      2. Or wait for timesfm to release a Python 3.12-compatible wheel.
+      3. Check for a conda-based install path: `conda install -c conda-forge timesfm`
+
+USAGE:
+    # With TimesFM (Python 3.11 + timesfm installed):
+    python analysis/forecast_timesfm.py
+
+    # Explicit baseline (any Python):
+    python analysis/forecast_timesfm.py --method baseline
+
+OUTPUT:
+    sample_data/forecasts/forecast_all.json  --  one file, all series
+
+FORECAST SCHEMA (per record):
+    commodity_code   str
+    city_id          str
+    city_name        str
+    method           str  ("timesfm_2.0" | "seasonal_naive_baseline")
+    generated_at     str  ISO 8601 UTC
+    horizon_days     int  (30)
+    history_end_date str  ISO 8601 -- last observed date
+    forecasts:  list of {
+        date   str  ISO 8601
+        point  float   (IDR/kg, point forecast)
+        p10    float   (IDR/kg, 10th percentile)
+        p90    float   (IDR/kg, 90th percentile)
+    }
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import math
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).parent.parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from analysis.price_anomaly import _load_all_rows, CITY_NAMES
+
+HORIZON = 30
+
+
+# ---------------------------------------------------------------------------
+# Seasonal-naive baseline (transparent fallback -- NOT TimesFM)
+# ---------------------------------------------------------------------------
+
+def _seasonal_naive_forecast(
+    series: list[tuple[datetime.date, float]],
+    horizon: int = HORIZON,
+) -> list[dict[str, Any]]:
+    """
+    Seasonal-naive: for day h, predict = median of same-calendar-month prices
+    observed in the training series.
+
+    Uncertainty band: +/- 1 MAD of the same-month observations.
+
+    This is a statistical method, not a foundation model.  It is labelled as
+    "seasonal_naive_baseline" everywhere it appears.
+    """
+    import numpy as np
+
+    prices = [p for _, p in series]
+    dates  = [d for d, _ in series]
+    arr    = np.array(prices, dtype=float)
+
+    # Build per-month (median, MAD) from the last 2 years of observed data
+    cutoff = dates[-1] - datetime.timedelta(days=2 * 365)
+    recent = [(d, p) for d, p in series if d >= cutoff]
+    if len(recent) < 30:
+        recent = series  # fall back to full series for short series
+
+    month_stats: dict[int, tuple[float, float]] = {}
+    from collections import defaultdict
+    month_vals: dict[int, list[float]] = defaultdict(list)
+    for d, p in recent:
+        month_vals[d.month].append(p)
+    for m, vals in month_vals.items():
+        v = np.array(vals)
+        med = float(np.median(v))
+        mad = float(np.median(np.abs(v - med)))
+        month_stats[m] = (med, mad)
+
+    # Overall fallback stats
+    overall_med = float(np.median(arr[-30:]))
+    overall_mad = float(np.median(np.abs(arr[-30:] - overall_med)))
+
+    last_date = dates[-1]
+    result = []
+    for h in range(1, horizon + 1):
+        target_date = last_date + datetime.timedelta(days=h)
+        med, mad = month_stats.get(target_date.month, (overall_med, overall_mad))
+        # CI: +/- 1.4826 * MAD (same scaling as the anomaly detector)
+        ci_half = 1.4826 * mad if mad > 0 else 0.05 * med
+        result.append({
+            "date":  target_date.isoformat(),
+            "point": round(med, 2),
+            "p10":   round(max(0, med - ci_half), 2),
+            "p90":   round(med + ci_half, 2),
+        })
+    return result
+
+
+# ---------------------------------------------------------------------------
+# TimesFM path (gated on successful import)
+# ---------------------------------------------------------------------------
+
+def _timesfm_available() -> bool:
+    try:
+        import timesfm  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def _timesfm_forecast(
+    series: list[tuple[datetime.date, float]],
+    horizon: int = HORIZON,
+    model_path: str = "google/timesfm-2.0-500m-pytorch",
+) -> list[dict[str, Any]]:
+    """
+    Run TimesFM 2.0 (PyTorch variant) on one price series.
+    Loads the model on first call (expensive — ~2 GB download + load).
+    Caller must ensure timesfm is installed and Python 3.10/3.11 is active.
+    """
+    import timesfm
+    import numpy as np
+
+    prices = np.array([p for _, p in series], dtype=float)
+    dates  = [d for d, _ in series]
+
+    # TimesFM 2.0 PyTorch API
+    tfm = timesfm.TimesFm(
+        hparams=timesfm.TimesFmHparams(
+            backend="cpu",
+            per_core_batch_size=1,
+            horizon_len=horizon,
+            num_heads=16,
+            use_positional_embedding=False,
+        ),
+        checkpoint=timesfm.TimesFmCheckpoint(
+            huggingface_repo_id=model_path,
+        ),
+    )
+
+    forecast_input = [prices]
+    freq           = [0]  # 0 = high-frequency (daily)
+
+    _, quantile_forecasts = tfm.forecast(
+        forecast_input,
+        freq=freq,
+        quantile_levels=[0.1, 0.5, 0.9],
+    )
+
+    # quantile_forecasts shape: (batch=1, horizon, 3)
+    qf = quantile_forecasts[0]  # (horizon, 3)
+    last_date = dates[-1]
+    result = []
+    for h in range(horizon):
+        target_date = last_date + datetime.timedelta(days=h + 1)
+        p10   = float(qf[h, 0])
+        point = float(qf[h, 1])
+        p90   = float(qf[h, 2])
+        result.append({
+            "date":  target_date.isoformat(),
+            "point": round(point, 2),
+            "p10":   round(max(0, p10), 2),
+            "p90":   round(p90, 2),
+        })
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main(
+    price_dir: Path,
+    out_dir: Path,
+    method: str,
+    model_path: str,
+) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / "forecast_all.json"
+
+    # Determine actual method
+    if method == "auto":
+        if _timesfm_available():
+            method = "timesfm"
+            print("TimesFM detected — will use real model.")
+        else:
+            method = "baseline"
+            print(
+                "WARNING: timesfm not importable on this Python version.\n"
+                "Falling back to seasonal_naive_baseline.\n"
+                "To get real TimesFM output, run with Python 3.10 or 3.11 + timesfm installed.\n"
+                "The output JSON will be labelled method=seasonal_naive_baseline."
+            )
+
+    generated_at = datetime.datetime.utcnow().isoformat() + "Z"
+    series_map   = _load_all_rows(price_dir)
+
+    print(f"Forecasting {len(series_map)} series ...")
+    all_records: list[dict[str, Any]] = []
+
+    for (commodity, city), series in sorted(series_map.items()):
+        if len(series) < 30:
+            print(f"  Skipping {commodity}/{city}: too short ({len(series)} obs)")
+            continue
+
+        if method == "timesfm":
+            try:
+                fc_points = _timesfm_forecast(series, horizon=HORIZON, model_path=model_path)
+                method_label = "timesfm_2.0"
+            except Exception as exc:
+                print(f"  TimesFM failed for {commodity}/{city}: {exc} — using baseline")
+                fc_points    = _seasonal_naive_forecast(series, horizon=HORIZON)
+                method_label = "seasonal_naive_baseline"
+        else:
+            fc_points    = _seasonal_naive_forecast(series, horizon=HORIZON)
+            method_label = "seasonal_naive_baseline"
+
+        all_records.append({
+            "commodity_code":   commodity,
+            "city_id":          city,
+            "city_name":        CITY_NAMES.get(city, city),
+            "method":           method_label,
+            "generated_at":     generated_at,
+            "horizon_days":     HORIZON,
+            "history_end_date": series[-1][0].isoformat(),
+            "forecasts":        fc_points,
+        })
+        print(f"  {commodity}/{city}: {method_label} — last obs {series[-1][0]}")
+
+    with out_path.open("w", encoding="utf-8") as fh:
+        json.dump(all_records, fh, ensure_ascii=False, separators=(",", ":"))
+
+    size_kb = out_path.stat().st_size / 1024
+    print(f"\nWrote {len(all_records)} series forecasts to {out_path}  ({size_kb:.1f} KB)")
+    if any(r["method"] == "seasonal_naive_baseline" for r in all_records):
+        print(
+            "\nNOTE: Output labelled 'seasonal_naive_baseline'.  "
+            "This is a transparent statistical baseline, NOT TimesFM.  "
+            "Re-run with Python 3.10/3.11 + timesfm installed for real forecasts."
+        )
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Precompute 30-day forecasts (TimesFM or seasonal baseline)."
+    )
+    parser.add_argument(
+        "--price-dir",
+        type=Path,
+        default=ROOT / "sample_data" / "price_history",
+    )
+    parser.add_argument(
+        "--out-dir",
+        type=Path,
+        default=ROOT / "sample_data" / "forecasts",
+    )
+    parser.add_argument(
+        "--method",
+        choices=["auto", "timesfm", "baseline"],
+        default="auto",
+        help=(
+            "auto: use TimesFM if available, else baseline. "
+            "baseline: force seasonal_naive_baseline (honest fallback). "
+            "timesfm: force TimesFM (will fail if not installed)."
+        ),
+    )
+    parser.add_argument(
+        "--model",
+        default="google/timesfm-2.0-500m-pytorch",
+        help="HuggingFace model ID for TimesFM 2.0 PyTorch variant.",
+    )
+    args = parser.parse_args()
+    main(args.price_dir, args.out_dir, args.method, args.model)

analysis/precompute_anomalies.py

@@ -0,0 +1,83 @@
+"""
+analysis/precompute_anomalies.py  --  Precompute all S-H-ESD anomalies to JSON.
+
+Run offline (locally or in CI) to produce sample_data/anomalies/anomalies_all.json.
+The backend serves from this file at runtime -- zero runtime computation on HF Space.
+
+Usage:
+    python analysis/precompute_anomalies.py
+    python analysis/precompute_anomalies.py --price-dir sample_data/price_history
+                                             --out-dir sample_data/anomalies
+
+Output schema per record:
+    date           str (ISO 8601, YYYY-MM-DD)
+    price          float
+    rolling_median float
+    deviation_pct  float
+    type           str  ("SPIKE" | "DROP")
+    score          float
+    commodity_code str
+    city_id        str
+    city_name      str
+    persistent     bool
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from analysis.price_anomaly import scan_all, CITY_NAMES
+
+
+def main(price_dir: Path, out_dir: Path) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / "anomalies_all.json"
+
+    print(f"Scanning {price_dir} ...")
+    anomalies = scan_all(price_dir, window=30, k=3.0, trend_window=30, persist=2)
+    print(f"  Found {len(anomalies)} anomalies across all series.")
+
+    # Serialise: convert datetime.date -> str, numpy floats -> float
+    records = []
+    for a in anomalies:
+        records.append({
+            "date":           a["date"].isoformat(),
+            "price":          float(a["price"]),
+            "rolling_median": float(a["rolling_median"]),
+            "deviation_pct":  float(a["deviation_pct"]),
+            "type":           a["type"],
+            "score":          float(a["score"]),
+            "commodity_code": a["commodity_code"],
+            "city_id":        a["city_id"],
+            "city_name":      CITY_NAMES.get(a["city_id"], a["city_id"]),
+            "persistent":     bool(a["persistent"]),
+        })
+
+    with out_path.open("w", encoding="utf-8") as fh:
+        json.dump(records, fh, ensure_ascii=False, separators=(",", ":"))
+
+    size_kb = out_path.stat().st_size / 1024
+    print(f"  Wrote {len(records)} records to {out_path}  ({size_kb:.1f} KB)")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Precompute S-H-ESD anomaly scan to JSON.")
+    parser.add_argument(
+        "--price-dir",
+        type=Path,
+        default=ROOT / "sample_data" / "price_history",
+    )
+    parser.add_argument(
+        "--out-dir",
+        type=Path,
+        default=ROOT / "sample_data" / "anomalies",
+    )
+    args = parser.parse_args()
+    main(args.price_dir, args.out_dir)

analysis/price_anomaly.py

@@ -0,0 +1,513 @@
+"""
+analysis/price_anomaly.py  --  S-H-ESD price anomaly detector for AgriFlow.
+
+METHOD: Seasonal-Hybrid ESD (S-H-ESD style)
+    Based on: Hochenbaum, Vallis, Kejariwal (2017), "Automatic Anomaly Detection in
+    the Cloud Via Statistical Learning", arXiv:1704.07706.
+    Validated against: Liu & Paparrizos, NeurIPS 2024, "Elephant in the Room" --
+    which confirms that robust statistical TSAD remains preferred over transformer-based
+    methods when interpretability and policy transparency are required.
+
+PIPELINE (per city x commodity series):
+    1. Decompose: price = trend + seasonal + residual
+       - trend    : rolling median over `trend_window` observations (robust to level
+                    shifts; same justification as original MAD detector).
+       - seasonal : median of (price - trend) grouped by *calendar month*.  Month
+                    granularity is correct for Indonesian agricultural seasonality
+                    (Ramadan, harvest cycles, year-end).  day-of-year would be noisier
+                    given the 5-year series length.
+       - residual : price - trend - seasonal
+    2. MAD on residual:
+       flag when |residual_t - rolling_median(residual)| > k * 1.4826 * MAD(residual)
+       using a rolling window of `window` observations over the residuals.
+    3. Persistence threshold: flag only if the breach persists for >= `persist` days
+       (default 2).  One-day noise (telur spike 16 Nov) is filtered.
+    4. MAD floor: if MAD(residual window) < `mad_floor_pct` * rolling_median(price),
+       skip flagging for that window.  Prevents over-sensitivity on low-volatility
+       commodities (beras_medium, beras_premium).
+    5. Min relative-change gate: flag only if |deviation_pct| >= `min_dev_pct`
+       (default 3 %).  Nominal IDR fluctuations in flat series are noise.
+
+WHY numpy-first (no statsmodels):
+    STL (statsmodels) would be cleaner for non-integer period series, but adds a
+    heavy dependency the project doesn't already carry.  Monthly medians over 5 years
+    of daily observations capture the dominant Indonesian agricultural seasonality
+    pattern with zero extra deps.  This is documented as a known simplification.
+
+HONEST LIMITATIONS:
+    1. Monthly seasonal component is estimated from only 4-5 years of data per month.
+       For commodities with irregular seasonality (Hijri calendar shifts, e.g. Ramadan
+       drifts ~11 days/year), the seasonal estimate will lag by up to 2 weeks.  This
+       means a Ramadan spike at an unusual calendar date may still be partially flagged.
+    2. Trend window is rolling median -- it will lag a step-change by up to trend_window/2
+       observations.  Residuals during a rapid price-regime shift will be elevated until
+       the trend catches up, producing a cluster of alerts at the breakpoint.  This is
+       intentional for the policy-alert use case.
+    3. Persistence filter is count-of-consecutive-flagged-observations, not calendar days.
+       For weekly-sampled data, N=2 means "two consecutive weeks", not "two days".
+    4. This is a robust statistical detector, not AI or ML.  It does not learn from
+       labelled anomaly data.  False negatives (missed true anomalies) and false positives
+       (flagged non-events) both exist.  The k and persist parameters must be tuned for
+       each deployment context.
+    5. beras_medium/premium are averages of two PIHPS sub-grades; single-grade commodities
+       will have somewhat sharper MAD estimates.
+
+Public API (backward-compatible with v1):
+    load_series(commodity_code, city_id, price_dir) -> list[(date, price)]
+    detect_anomalies(series, window=30, k=3.0, trend_window=30,
+                     persist=2, mad_floor_pct=0.005, min_dev_pct=3.0) -> list[dict]
+    scan_all(price_dir, window=30, k=3.0, trend_window=30,
+             persist=2, mad_floor_pct=0.005, min_dev_pct=3.0) -> list[dict]
+
+Output schema (each dict):
+    date            datetime.date
+    price           float           observed price (IDR/kg)
+    rolling_median  float           rolling median of residuals at this point
+    deviation_pct   float           (price - trend) / trend * 100, signed  [v2: vs trend not raw median]
+    type            str             'SPIKE' or 'DROP'
+    score           float           |residual dev| / (1.4826 * MAD(residual)), higher = more anomalous
+    commodity_code  str             populated by scan_all; empty str from detect_anomalies
+    city_id         str             populated by scan_all; empty str from detect_anomalies
+    persistent      bool            True if breach lasted >= persist days
+"""
+
+from __future__ import annotations
+
+import csv
+import datetime
+from collections import defaultdict
+from pathlib import Path
+from typing import List, Tuple, Dict, Any
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Commodity code normalisation (mirrors db/price_ingest.py)
+# ---------------------------------------------------------------------------
+
+_COMMODITY_MAP: Dict[str, str] = {
+    "bawang_merah":   "bawang_merah",
+    "bawang_putih":   "bawang_putih",
+    "daging_ayam":    "daging_ayam",
+    "telur_ayam":     "telur_ayam",
+    "cabe_rawit":     "cabai_rawit",
+    "beras_medium_1": "beras_medium",
+    "beras_medium_2": "beras_medium",
+    "beras_super_1":  "beras_premium",
+    "beras_super_2":  "beras_premium",
+}
+
+# Human-readable city names for reporting (IHK Jatim cities)
+CITY_NAMES: Dict[str, str] = {
+    "3509": "Jember",
+    "3510": "Banyuwangi",
+    "3529": "Sumenep",
+    "3571": "Kota Kediri",
+    "3573": "Kota Malang",
+    "3574": "Kota Probolinggo",
+    "3577": "Kota Madiun",
+    "3578": "Kota Surabaya",
+}
+
+
+# ---------------------------------------------------------------------------
+# Internal: load raw CSV
+# ---------------------------------------------------------------------------
+
+def _read_csv_rows(csv_path: Path) -> List[Dict[str, Any]]:
+    """
+    Read one *_cleaned.csv; return list of dicts with canonical commodity codes.
+    Silently skips rows with unrecognised commodity codes.
+    """
+    rows = []
+    with csv_path.open(newline="", encoding="utf-8") as fh:
+        for row in csv.DictReader(fh):
+            raw_code = row["commodity_code"].strip()
+            canonical = _COMMODITY_MAP.get(raw_code)
+            if canonical is None:
+                continue
+            rows.append({
+                "date": datetime.date.fromisoformat(row["date"].strip()),
+                "city_id": row["city_id"].strip(),
+                "commodity_code": canonical,
+                "price": float(row["price_per_kg"].strip()),
+            })
+    return rows
+
+
+def _load_all_rows(price_dir: Path) -> Dict[Tuple[str, str], List[Tuple[datetime.date, float]]]:
+    """
+    Load all *_cleaned.csv; return (commodity_code, city_id) -> sorted [(date, price)].
+    Multiple sub-grades on the same (date, city) are averaged.
+    """
+    price_dir = Path(price_dir)
+    if not price_dir.is_dir():
+        raise FileNotFoundError(f"Price directory not found: {price_dir}")
+
+    accumulated: Dict[Tuple[str, str, datetime.date], List[float]] = {}
+    for csv_path in sorted(price_dir.glob("*_cleaned.csv")):
+        for row in _read_csv_rows(csv_path):
+            key = (row["commodity_code"], row["city_id"], row["date"])
+            accumulated.setdefault(key, []).append(row["price"])
+
+    series_map: Dict[Tuple[str, str], List[Tuple[datetime.date, float]]] = {}
+    for (commodity, city, date), prices in accumulated.items():
+        avg_price = sum(prices) / len(prices)
+        series_map.setdefault((commodity, city), []).append((date, avg_price))
+
+    for key in series_map:
+        series_map[key].sort(key=lambda x: x[0])
+
+    return series_map
+
+
+# ---------------------------------------------------------------------------
+# Decomposition: trend + seasonal via numpy (no external dep)
+# ---------------------------------------------------------------------------
+
+def _rolling_median(arr: np.ndarray, window: int) -> np.ndarray:
+    """
+    Rolling median, left-aligned (uses the `window` most recent values up to t).
+    Positions with fewer than `window` values use the available prefix (min_periods=1).
+    Returns array same length as arr.
+    """
+    n = len(arr)
+    result = np.empty(n, dtype=float)
+    for t in range(n):
+        lo = max(0, t - window + 1)
+        result[t] = float(np.median(arr[lo : t + 1]))
+    return result
+
+
+def _decompose(
+    prices: np.ndarray,
+    dates: List[datetime.date],
+    trend_window: int,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Decompose a price series into (trend, seasonal, residual).
+
+    trend    = rolling median over trend_window observations
+    seasonal = per-month median of (price - trend), applied back to each observation
+               by month.  This captures the dominant Indonesian agricultural calendar
+               (Ramadan, harvest, year-end) without requiring statsmodels.
+    residual = price - trend - seasonal
+
+    Design notes:
+    - Month-level seasonality (12 bins) is appropriate here: the dataset spans 5 years
+      of daily observations.  Day-of-year (365 bins) would produce 5 samples/bin on
+      average -- too noisy.
+    - Seasonal is estimated on detrended prices (price - trend), not raw prices, to
+      avoid trend contamination in the seasonal component.
+    - Seasonal is set to 0 for any month with fewer than 2 detrended observations
+      (edge case for very short or gappy series).
+    """
+    n = len(prices)
+    trend = _rolling_median(prices, trend_window)
+    detrended = prices - trend
+
+    # Build month -> median of detrended prices
+    month_vals: Dict[int, List[float]] = defaultdict(list)
+    for i, d in enumerate(dates):
+        month_vals[d.month].append(detrended[i])
+
+    monthly_median: Dict[int, float] = {}
+    for m, vals in month_vals.items():
+        monthly_median[m] = float(np.median(vals)) if len(vals) >= 2 else 0.0
+
+    seasonal = np.array(
+        [monthly_median.get(d.month, 0.0) for d in dates],
+        dtype=float,
+    )
+
+    residual = prices - trend - seasonal
+    return trend, seasonal, residual
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def load_series(
+    commodity_code: str,
+    city_id: str,
+    price_dir: str | Path,
+) -> List[Tuple[datetime.date, float]]:
+    """
+    Load the price time series for one (commodity_code, city_id) pair.
+
+    Parameters
+    ----------
+    commodity_code : str
+        AgriFlow canonical code (e.g. "cabai_rawit", "bawang_merah").
+        Also accepts raw PIHPS codes (e.g. "cabe_rawit") -- normalised automatically.
+    city_id : str
+        IHK city identifier (e.g. "3578" for Surabaya).
+    price_dir : str or Path
+        Directory containing *_cleaned.csv files.
+
+    Returns
+    -------
+    list of (datetime.date, float)
+        Sorted by date ascending.  Empty list if no data found.
+
+    Raises
+    ------
+    FileNotFoundError
+        If price_dir does not exist.
+    """
+    canonical = _COMMODITY_MAP.get(commodity_code, commodity_code)
+    series_map = _load_all_rows(Path(price_dir))
+    return series_map.get((canonical, city_id), [])
+
+
+def detect_anomalies(
+    series: List[Tuple[datetime.date, float]],
+    window: int = 30,
+    k: float = 3.0,
+    trend_window: int = 30,
+    persist: int = 2,
+    mad_floor_pct: float = 0.005,
+    min_dev_pct: float = 3.0,
+) -> List[Dict[str, Any]]:
+    """
+    Detect price anomalies using S-H-ESD: deseasonalize then apply rolling MAD
+    on the residuals.
+
+    Steps
+    -----
+    1. Decompose series: trend (rolling median) + seasonal (monthly median of
+       detrended) + residual.
+    2. Apply rolling MAD on residuals with threshold k * 1.4826 * MAD.
+    3. Persistence filter: retain only flags that appear in a streak of >= persist
+       consecutive observations.
+    4. MAD floor: skip windows where MAD(residual) < mad_floor_pct * rolling median
+       of raw prices (protects beras_medium / beras_premium from over-sensitivity).
+    5. Min relative change gate: skip flags where |price - trend| / trend * 100
+       < min_dev_pct (filters nominal IDR noise).
+
+    Parameters
+    ----------
+    series : list of (datetime.date, float)
+        Price observations, sorted ascending.
+    window : int, default 30
+        Rolling window for MAD on residuals.  Minimum to flag is window (same as v1).
+    k : float, default 3.0
+        Sensitivity multiplier.  k=3 corresponds to ~0.3 % tail on Gaussian data;
+        effectively ~1-2 % on fat-tailed commodity residuals after deseasonalisation.
+    trend_window : int, default 30
+        Rolling window for trend estimation.  Larger = smoother trend but more lag.
+        Set equal to `window` by default so the two rolling calculations are aligned.
+    persist : int, default 2
+        Minimum consecutive flagged observations for a flag to be reported.
+        Setting persist=1 disables the persistence filter (reverts to v1 behaviour).
+    mad_floor_pct : float, default 0.005
+        MAD floor as a fraction of the rolling median of raw prices.  E.g. 0.005 means
+        the MAD must be at least 0.5 % of the current price level.  Prevents
+        over-sensitivity on low-volatility series (beras).
+    min_dev_pct : float, default 3.0
+        Minimum absolute deviation from trend (as % of trend) to flag.
+        Filters nominal fluctuations that pass MAD test only due to very small MAD.
+
+    Returns
+    -------
+    list of dict, each with keys:
+        date            datetime.date
+        price           float           observed price (IDR/kg)
+        rolling_median  float           rolling median of RESIDUALS at this point
+        deviation_pct   float           (price - trend) / trend * 100, signed
+        type            str             'SPIKE' or 'DROP'
+        score           float           |residual dev| in MAD units
+        commodity_code  str             populated by scan_all; empty str here
+        city_id         str             populated by scan_all; empty str here
+        persistent      bool            True if streak >= persist
+
+    Notes
+    -----
+    - Series shorter than window returns empty list (same as v1).
+    - MAD == 0 on residual window: no flag (perfectly flat residuals mean no
+      anomalous structure).
+    - Result sorted by score descending.
+    """
+    if len(series) < window:
+        return []
+
+    dates = [d for d, _ in series]
+    prices = np.array([p for _, p in series], dtype=float)
+    n = len(prices)
+
+    # Step 1: decompose
+    trend, seasonal, residual = _decompose(prices, dates, trend_window)
+
+    # Step 2: rolling MAD on residuals — same left-aligned logic as v1
+    raw_flags: List[Dict[str, Any]] = []
+
+    for t in range(window - 1, n):
+        res_window = residual[t - window + 1 : t + 1]
+        roll_med_res = float(np.median(res_window))
+        abs_devs = np.abs(res_window - roll_med_res)
+        mad = float(np.median(abs_devs))
+
+        raw_dev_res = residual[t] - roll_med_res
+
+        # --- gate logic ---
+        if mad == 0.0:
+            # Perfectly flat residual window: any non-zero deviation is a
+            # step-change (e.g. spike into a perfectly flat series).  We skip
+            # the MAD floor (which would fire trivially on mad==0) and score the
+            # deviation as percentage of the current price level instead.
+            if raw_dev_res == 0.0:
+                continue  # truly flat: nothing to flag
+            price_level = float(np.median(prices[t - window + 1 : t + 1]))
+            score = float(abs(raw_dev_res) / price_level) * 100.0 if price_level > 0 else 0.0
+            # still apply min relative-change gate
+            raw_price_dev = prices[t] - trend[t]
+            dev_pct = (raw_price_dev / trend[t]) * 100.0 if trend[t] > 0 else 0.0
+            if abs(dev_pct) < min_dev_pct:
+                continue
+            raw_flags.append({
+                "idx":            t,
+                "date":           dates[t],
+                "price":          float(prices[t]),
+                "rolling_median": round(roll_med_res, 2),
+                "deviation_pct":  round(dev_pct, 2),
+                "type":           "SPIKE" if raw_price_dev > 0 else "DROP",
+                "score":          round(score, 3),
+                "commodity_code": "",
+                "city_id":        "",
+                "persistent":     False,
+            })
+            continue
+
+        # Step 4: MAD floor -- skip if both (a) MAD is tiny relative to price
+        # level AND (b) the current residual deviation is also tiny.
+        # This protects against over-sensitivity on low-volatility series
+        # (beras_medium / beras_premium) where the residual MAD and the
+        # deviation itself are both small IDR amounts.
+        # We guard condition (b) so that a genuine large anomaly (large |dev|)
+        # is never blocked even if the window MAD happens to be below the floor.
+        price_level = float(np.median(prices[t - window + 1 : t + 1]))
+        if price_level > 0 and mad < mad_floor_pct * price_level:
+            # Only skip if the deviation is also small (< 2x the floor threshold).
+            # A 100k deviation on a 54k series must NOT be blocked by the floor.
+            dev_abs = abs(raw_dev_res)
+            floor_val = mad_floor_pct * price_level
+            if dev_abs < 2.0 * floor_val:
+                continue
+
+        threshold = k * 1.4826 * mad
+        score = float(abs(raw_dev_res) / (1.4826 * mad))
+
+        if abs(raw_dev_res) > threshold:
+            # Step 5: min relative-change gate (vs trend, not vs raw median)
+            raw_price_dev = prices[t] - trend[t]
+            dev_pct = (raw_price_dev / trend[t]) * 100.0 if trend[t] > 0 else 0.0
+            if abs(dev_pct) < min_dev_pct:
+                continue
+
+            raw_flags.append({
+                "idx":            t,
+                "date":           dates[t],
+                "price":          float(prices[t]),
+                "rolling_median": round(roll_med_res, 2),
+                "deviation_pct":  round(dev_pct, 2),
+                "type":           "SPIKE" if raw_price_dev > 0 else "DROP",
+                "score":          round(score, 3),
+                "commodity_code": "",
+                "city_id":        "",
+                "persistent":     False,  # filled in step 3
+            })
+
+    # Step 3: persistence filter
+    # A flag is "persistent" if the consecutive run of flagged indices that
+    # contains it has total length >= persist.
+    # Algorithm: for each flagged index, walk backward to the run start, then
+    # measure the run forward from there.  Cache run-start -> run-length to
+    # avoid O(n^2) re-computation for long streaks.
+    flagged_indices = {f["idx"] for f in raw_flags}
+    run_length_cache: Dict[int, int] = {}
+
+    def _run_length(idx: int) -> int:
+        # Walk to run start
+        start = idx
+        while (start - 1) in flagged_indices:
+            start -= 1
+        if start in run_length_cache:
+            return run_length_cache[start]
+        # Measure run from start
+        length = 0
+        cur = start
+        while cur in flagged_indices:
+            length += 1
+            cur += 1
+        run_length_cache[start] = length
+        return length
+
+    anomalies: List[Dict[str, Any]] = []
+
+    for flag in raw_flags:
+        is_persistent = _run_length(flag["idx"]) >= persist
+        flag["persistent"] = is_persistent
+        if is_persistent:
+            anomalies.append(flag)
+
+    # Remove internal idx key
+    for a in anomalies:
+        del a["idx"]
+
+    anomalies.sort(key=lambda x: x["score"], reverse=True)
+    return anomalies
+
+
+def scan_all(
+    price_dir: str | Path,
+    window: int = 30,
+    k: float = 3.0,
+    trend_window: int = 30,
+    persist: int = 2,
+    mad_floor_pct: float = 0.005,
+    min_dev_pct: float = 3.0,
+) -> List[Dict[str, Any]]:
+    """
+    Scan all (commodity_code, city_id) combinations and return all detected
+    anomalies, sorted by score descending.
+
+    Parameters
+    ----------
+    price_dir : str or Path
+        Directory containing *_cleaned.csv files.
+    window, k, trend_window, persist, mad_floor_pct, min_dev_pct
+        Passed directly to detect_anomalies().
+
+    Returns
+    -------
+    list of dict
+        Same schema as detect_anomalies() output, with commodity_code and
+        city_id populated.  Sorted by score descending.
+
+    Raises
+    ------
+    FileNotFoundError
+        If price_dir does not exist.
+    """
+    series_map = _load_all_rows(Path(price_dir))
+    all_anomalies: List[Dict[str, Any]] = []
+
+    for (commodity, city), series in series_map.items():
+        anomalies = detect_anomalies(
+            series,
+            window=window,
+            k=k,
+            trend_window=trend_window,
+            persist=persist,
+            mad_floor_pct=mad_floor_pct,
+            min_dev_pct=min_dev_pct,
+        )
+        for a in anomalies:
+            a["commodity_code"] = commodity
+            a["city_id"] = city
+        all_anomalies.extend(anomalies)
+
+    all_anomalies.sort(key=lambda x: x["score"], reverse=True)
+    return all_anomalies

analysis/run_anomaly_report.py

@@ -0,0 +1,190 @@
+"""
+analysis/run_anomaly_report.py  --  Price anomaly report for AgriFlow.
+
+Usage (from project root):
+    python analysis/run_anomaly_report.py
+    python analysis/run_anomaly_report.py --top 20 --k 2.5
+    python analysis/run_anomaly_report.py --window 14 --k 3.0 --commodity cabai_rawit
+    python analysis/run_anomaly_report.py --compare   # show BEFORE vs AFTER flag counts
+
+Method v2: S-H-ESD (Seasonal-Hybrid ESD).
+  v1 was rolling-median + MAD on raw prices; this is deseasonalise first,
+  then MAD on residuals, with persistence and low-vol gates.
+  Result: ~70 % reduction in flag count (14,261 -> 4,192 on 2021-2025 Jatim data).
+
+No external API calls; fully offline.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Force UTF-8 stdout/stderr on Windows (default cp1252 breaks "Rp", arrows, etc.)
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except (AttributeError, OSError):
+        pass
+
+# Allow running from project root without pip install
+_ROOT = Path(__file__).parent.parent
+if str(_ROOT) not in sys.path:
+    sys.path.insert(0, str(_ROOT))
+
+from analysis.price_anomaly import scan_all, CITY_NAMES
+
+PRICE_DIR = _ROOT / "sample_data" / "price_history"
+
+COMMODITY_LABELS = {
+    "cabai_rawit":  "Cabai Rawit",
+    "bawang_merah": "Bawang Merah",
+    "bawang_putih": "Bawang Putih",
+    "daging_ayam":  "Daging Ayam",
+    "telur_ayam":   "Telur Ayam",
+    "beras_medium": "Beras Medium",
+    "beras_premium":"Beras Premium",
+}
+
+
+def _fmt_price(p: float) -> str:
+    return f"Rp {p:,.0f}/kg"
+
+
+def _run_v1_count() -> int:
+    """
+    Reproduce the v1 (raw-price rolling-MAD) flag count for BEFORE/AFTER comparison.
+    Uses the same k=3.0, window=30 as the default.
+    """
+    from analysis.price_anomaly import _load_all_rows
+    import numpy as np
+
+    series_map = _load_all_rows(PRICE_DIR)
+    total = 0
+    window = 30
+    k = 3.0
+
+    for (commodity, city), series in series_map.items():
+        if len(series) < window:
+            continue
+        prices = np.array([p for _, p in series], dtype=float)
+        n = len(prices)
+        for t in range(window - 1, n):
+            w = prices[t - window + 1 : t + 1]
+            roll_med = float(np.median(w))
+            mad = float(np.median(np.abs(w - roll_med)))
+            if mad == 0.0:
+                if prices[t] != roll_med:
+                    total += 1
+                continue
+            if abs(prices[t] - roll_med) > k * 1.4826 * mad:
+                total += 1
+
+    return total
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="AgriFlow price anomaly report (S-H-ESD v2)")
+    parser.add_argument("--top",      type=int,   default=15,   help="Top N to show (default 15)")
+    parser.add_argument("--window",   type=int,   default=30,   help="Rolling window size (default 30)")
+    parser.add_argument("--k",        type=float, default=3.0,  help="MAD sensitivity k (default 3.0)")
+    parser.add_argument("--persist",  type=int,   default=2,    help="Persistence threshold (default 2)")
+    parser.add_argument("--commodity", type=str,  default=None, help="Filter to one commodity code")
+    parser.add_argument("--compare",  action="store_true",
+                        help="Show BEFORE (v1 raw-price MAD) vs AFTER (S-H-ESD v2) counts")
+    args = parser.parse_args()
+
+    print()
+    print("=" * 72)
+    print("  AgriFlow -- Deteksi Anomali Harga (S-H-ESD v2, PIHPS Jatim 2021-2025)")
+    print("=" * 72)
+    print(f"  Data      : {PRICE_DIR}")
+    print(f"  Window    : {args.window} observations")
+    print(f"  Threshold : k={args.k}  (|dev| > {args.k} * 1.4826 * MAD on RESIDUAL)")
+    print(f"  Persist   : >= {args.persist} consecutive flagged observations")
+    print(f"  Method    : S-H-ESD -- deseasonalise, then robust MAD on residual")
+    print(f"              (Hochenbaum/Vallis/Kejariwal arXiv:1704.07706)")
+    print(f"              NOT 'AI'; interpretable statistical detector")
+    print()
+
+    # BEFORE/AFTER comparison
+    if args.compare:
+        print("  Computing BEFORE count (v1 rolling-MAD on raw prices) ...", end=" ", flush=True)
+        before_count = _run_v1_count()
+        print(f"done. {before_count:,} flags.")
+
+    print("  Running S-H-ESD v2 ...", end=" ", flush=True)
+    anomalies = scan_all(
+        PRICE_DIR,
+        window=args.window,
+        k=args.k,
+        persist=args.persist,
+    )
+    after_count = len(anomalies)
+    print(f"done. {after_count:,} anomaly points detected.")
+
+    if args.compare:
+        reduction = (before_count - after_count) / before_count * 100
+        print()
+        print("  BEFORE vs AFTER:")
+        print(f"    v1 (raw-price rolling-MAD)  : {before_count:>7,} flags")
+        print(f"    v2 (S-H-ESD, deseasonalised): {after_count:>7,} flags")
+        print(f"    Reduction                   : {reduction:>6.1f} %")
+
+    print()
+
+    if args.commodity:
+        anomalies = [a for a in anomalies if a["commodity_code"] == args.commodity]
+        print(f"  Filtered to '{args.commodity}': {len(anomalies):,} anomalies.")
+        print()
+
+    if not anomalies:
+        print("  No anomalies found for the given filters.")
+        return
+
+    top = anomalies[: args.top]
+
+    print(f"  Top {len(top)} anomalies ranked by score (highest first):")
+    print()
+    print(f"  {'#':>3}  {'Date':<12}  {'Type':<6}  {'Commodity':<15}  {'Kota':<20}"
+          f"  {'Price':>14}  {'Dev%':>8}  {'Score':>7}  {'Persist':<8}")
+    print("  " + "-" * 106)
+
+    for i, a in enumerate(top, 1):
+        city_name = CITY_NAMES.get(a["city_id"], a["city_id"])
+        comm_label = COMMODITY_LABELS.get(a["commodity_code"], a["commodity_code"])
+        sign = "+" if a["deviation_pct"] > 0 else ""
+        persist_marker = "YES" if a["persistent"] else "no"
+        print(
+            f"  {i:>3}  {str(a['date']):<12}  {a['type']:<6}  {comm_label:<15}  "
+            f"{city_name:<20}  {_fmt_price(a['price']):>14}  "
+            f"{sign}{a['deviation_pct']:>6.1f}%  {a['score']:>7.2f}  {persist_marker:<8}"
+        )
+
+    print()
+    print("  Catatan keterbatasan (S-H-ESD v2):")
+    print("  - Seasonal komponen: monthly median -- Ramadan (Hijri) drifts ~11 hr/thn;")
+    print("    spike Ramadan di tanggal masehi tak biasa masih bisa muncul parsial.")
+    print("  - Trend window = rolling median; lag 15-obs saat price-regime shift cepat.")
+    print("  - Persist filter = consecutive observations, bukan hari kalender.")
+    print("    Untuk data mingguan, persist=2 = '2 minggu berturut-turut'.")
+    print("  - beras_medium/premium: rata-rata 2 sub-grade PIHPS; anomali sedikit")
+    print("    konservatif dibanding single-grade.")
+    print()
+
+    # Summary by commodity
+    from collections import Counter
+    by_comm = Counter(a["commodity_code"] for a in anomalies)
+    print("  Total anomalies per commodity (semua, bukan hanya top N):")
+    for comm, count in by_comm.most_common():
+        label = COMMODITY_LABELS.get(comm, comm)
+        persistent_count = sum(1 for a in anomalies if a["commodity_code"] == comm and a["persistent"])
+        print(f"    {label:<20} : {count:>5} points  ({persistent_count} persistent)")
+    print()
+    print("=" * 72)
+
+
+if __name__ == "__main__":
+    main()

benchmarks/_metrics.py

@@ -0,0 +1,241 @@
+"""
+benchmarks/_metrics.py — Pure equity metrics helpers.
+
+No engine imports. All functions are pure (no side effects, no I/O).
+These are the five metrics columns in the baseline comparison table.
+
+Metric definitions
+------------------
+total_deficit_covered
+    Volume-weighted coverage: sum of min(matched, demanded) across all
+    (kab, commodity, segment) keys divided by total demand volume.
+    This is tons fulfilled / tons demanded, NOT count of kab covered.
+    A 200-ton deficit that is 50% filled counts more than a 10-ton
+    deficit that is 100% filled.
+
+gini
+    Weighted Gini coefficient from the Lorenz curve formulation:
+
+        G = Σᵢ Σⱼ wᵢ wⱼ |rᵢ − rⱼ| / (2 (Σwᵢ)² r̄)
+
+    where:
+        rᵢ  = fulfillment ratio for node i (matched_tons / demand_tons)
+        wᵢ  = demand volume weight (demand_tons for node i)
+        r̄   = weighted mean fulfillment ratio
+
+    Verification invariants:
+        gini_weighted([1,1,1,1], equal weights) ≈ 0.0   (perfectly equal)
+        gini_weighted([1,0,0,0], equal weights) > 0.6    (maximum inequality)
+        uniform allocation  → Gini ≈ 0 (everyone gets same ratio)
+        pure greedy         → Gini highest (best nodes get everything first)
+
+atkinson
+    Atkinson index A(ε) = 1 − (1/μ) * (Σᵢ wᵢ rᵢ^(1−ε) / Σᵢ wᵢ)^(1/(1−ε))
+    for ε ≠ 1.  For ε = 1: A(1) = 1 − exp(Σᵢ wᵢ ln(rᵢ) / Σᵢ wᵢ) / μ.
+    Reported at ε=0.5 (moderate inequality aversion) and ε=1.0 (strong).
+    wᵢ = demand_tons weight.  rᵢ values of 0 handled by clamping to 1e-9
+    before log, consistent with standard practice.
+
+min_fulfillment
+    Leximin gap = the single worst fulfillment ratio across all nodes.
+    One number per strategy; higher is better.
+
+kab_fulfillment
+    Volume-weighted fulfillment ratio for a single kabupaten across all
+    its (commodity, segment) demand nodes.
+    Used for Sampang (3527) and Bangkalan (3526) headline numbers.
+"""
+from __future__ import annotations
+
+import math
+from typing import Dict, Tuple
+
+
+# Key type used throughout: (kab_id, commodity_code, segment_value) -> float
+_Key = Tuple[str, str, str]
+
+
+def fulfillment_by_node(
+    matched_tons: Dict[_Key, float],
+    demand_tons: Dict[_Key, float],
+) -> Dict[_Key, float]:
+    """
+    Per-node fulfillment ratio capped at 1.0.
+
+    Args:
+        matched_tons: dict key -> tons matched (may be missing for unmatched nodes)
+        demand_tons:  dict key -> tons demanded (positive values only)
+
+    Returns:
+        dict key -> ratio in [0.0, 1.0] for every key with demand_tons > 0.
+    """
+    return {
+        k: min(1.0, matched_tons.get(k, 0.0) / v)
+        for k, v in demand_tons.items()
+        if v > 0
+    }
+
+
+def total_deficit_covered(
+    matched_tons: Dict[_Key, float],
+    demand_tons: Dict[_Key, float],
+) -> float:
+    """
+    Volume-weighted coverage ratio: tons fulfilled / tons demanded.
+
+    This is NOT a count of kabupaten covered — it weights each node by
+    its demand volume so a 200-ton deficit that is half-filled (100t)
+    contributes more than a 10-ton deficit that is fully filled (10t).
+
+    Returns a float in [0.0, 1.0].
+    """
+    total = sum(demand_tons.values())
+    if total == 0:
+        return 0.0
+    covered = sum(
+        min(matched_tons.get(k, 0.0), v) for k, v in demand_tons.items()
+    )
+    return covered / total
+
+
+def gini(
+    matched_tons: Dict[_Key, float],
+    demand_tons: Dict[_Key, float],
+) -> float:
+    """
+    Weighted Gini from the Lorenz curve mean-absolute-difference formula.
+
+        G = Σᵢ Σⱼ wᵢ wⱼ |rᵢ − rⱼ| / (2 (Σwᵢ)² r̄)
+
+    wᵢ = demand_tons[i]  (volume weight)
+    rᵢ = fulfillment ratio for node i, capped at 1.0
+
+    Returns 0.0 when all fulfillment ratios are identical (uniform allocation).
+    Returns near-maximum when one node gets everything and others get nothing.
+
+    Verification:
+        gini({k: 1 for all k}, equal weights) == 0.0
+        gini({k: 0 for all k except one}, equal weights) > 0.6
+        uniform allocation produces Gini ≈ 0 (all ratios equal)
+    """
+    nodes = [(k, v) for k, v in demand_tons.items() if v > 0]
+    if not nodes:
+        return 0.0
+
+    ratios = [min(1.0, matched_tons.get(k, 0.0) / v) for k, v in nodes]
+    weights = [v for _, v in nodes]
+
+    w_sum = sum(weights)
+    if w_sum == 0:
+        return 0.0
+
+    # Weighted mean fulfillment
+    r_bar = sum(w * r for w, r in zip(weights, ratios)) / w_sum
+    if r_bar == 0:
+        return 0.0
+
+    # Double-sum formulation: O(n²) but n is at most ~38*19*4 ≈ 2888 for Jatim.
+    # Formula: G = Σ_all_ij wᵢwⱼ|rᵢ−rⱼ| / (2 w_sum² r̄)
+    # Σ_all_ij = 2 * Σ_{i<j}  (since |rᵢ−rⱼ| is symmetric and diagonal is 0).
+    # Therefore: G = 2*Σ_{i<j} wᵢwⱼ|rᵢ−rⱼ| / (2 w_sum² r̄) = Σ_{i<j} / (w_sum² r̄).
+    total = 0.0
+    n = len(ratios)
+    for i in range(n):
+        for j in range(i + 1, n):
+            total += weights[i] * weights[j] * abs(ratios[i] - ratios[j])
+    return total / (w_sum ** 2 * r_bar)
+
+
+def atkinson(
+    matched_tons: Dict[_Key, float],
+    demand_tons: Dict[_Key, float],
+    epsilon: float = 0.5,
+) -> float:
+    """
+    Atkinson inequality index A(ε).
+
+    For ε ≠ 1:
+        A(ε) = 1 − (1/μ) * (Σᵢ wᵢ rᵢ^(1−ε) / Σᵢ wᵢ)^(1/(1−ε))
+
+    For ε = 1 (limiting case):
+        A(1) = 1 − exp(Σᵢ wᵢ ln(rᵢ) / Σᵢ wᵢ) / μ
+
+    wᵢ = demand_tons weight.
+    rᵢ = fulfillment ratio capped at 1.0.
+    rᵢ = 0 clamped to 1e-9 before log (standard handling).
+
+    Returns value in [0.0, 1.0]; higher means more inequality.
+    """
+    nodes = [(k, v) for k, v in demand_tons.items() if v > 0]
+    if not nodes:
+        return 0.0
+
+    ratios = [min(1.0, matched_tons.get(k, 0.0) / v) for k, v in nodes]
+    weights = [v for _, v in nodes]
+
+    w_sum = sum(weights)
+    if w_sum == 0:
+        return 0.0
+
+    mu = sum(w * r for w, r in zip(weights, ratios)) / w_sum
+    if mu == 0:
+        return 1.0  # everyone gets nothing → maximum inequality by convention
+
+    if abs(epsilon - 1.0) < 1e-9:
+        # Geometric mean formulation
+        log_sum = sum(
+            w * math.log(max(r, 1e-9)) for w, r in zip(weights, ratios)
+        )
+        geom_mean = math.exp(log_sum / w_sum)
+        return 1.0 - geom_mean / mu
+    else:
+        power = 1.0 - epsilon
+        moment = sum(
+            w * (max(r, 1e-9) ** power) for w, r in zip(weights, ratios)
+        ) / w_sum
+        ede = moment ** (1.0 / power)
+        return 1.0 - ede / mu
+
+
+def min_fulfillment(
+    matched_tons: Dict[_Key, float],
+    demand_tons: Dict[_Key, float],
+) -> float:
+    """
+    Leximin gap: fulfillment ratio of the single worst-served demand node.
+
+    A strategy that sacrifices one kab entirely will score 0.0 here.
+    Higher is better.
+
+    Returns 0.0 if there are no demand nodes.
+    """
+    nodes = [(k, v) for k, v in demand_tons.items() if v > 0]
+    if not nodes:
+        return 0.0
+    ratios = [min(1.0, matched_tons.get(k, 0.0) / v) for k, v in nodes]
+    return min(ratios)
+
+
+def kab_fulfillment(
+    matched_tons: Dict[_Key, float],
+    demand_tons: Dict[_Key, float],
+    kab_id: str,
+) -> float:
+    """
+    Volume-weighted fulfillment ratio for a single kabupaten across all
+    its (commodity, segment) demand nodes.
+
+    Used for Sampang (3527) and Bangkalan (3526) headline pitch numbers.
+
+    Returns 0.0 if kab_id has no demand entries.
+    """
+    kab_demand = {k: v for k, v in demand_tons.items() if k[0] == kab_id}
+    if not kab_demand:
+        return 0.0
+    total_demand = sum(kab_demand.values())
+    if total_demand == 0:
+        return 0.0
+    total_matched = sum(
+        min(matched_tons.get(k, 0.0), v) for k, v in kab_demand.items()
+    )
+    return total_matched / total_demand

benchmarks/anomaly_detector_gap.py

@@ -0,0 +1,279 @@
+"""
+benchmarks/anomaly_detector_gap.py — Quantifies the gap between AgriFlow's TWO
+price-anomaly detectors on the project's own real data.
+
+BACKGROUND
+----------
+Two detectors exist in the codebase, both in the production path:
+
+  matching_engine/engine.py:62  detect_price_anomaly(node, historical_median,
+      historical_std) -- z_score = |price - median| / std, flag if > 3.0
+      (PRICE_ANOMALY_SIGMA). This is what actually gates matching: called at
+      engine.py:416 and :429 inside run_matching()'s D3 preprocessing, and a
+      flagged node is DROPPED from the surplus/deficit pool entirely (not just
+      down-weighted).
+
+  analysis/price_anomaly.py    detect_anomalies() -- S-H-ESD: deseasonalise
+      (rolling-median trend + monthly seasonal), then robust MAD on the
+      residual, with a persistence filter. This is validated against the
+      literature (Hochenbaum/Vallis/Kejariwal 2017) and is what feeds the
+      dashboard anomaly panel / API -- NOT the matching engine.
+
+detect_price_anomaly's std is non-robust: a real outlier inflates std, which
+shrinks the z-score of ALL points (including the outlier itself and future
+genuine anomalies) -- the classic "masking effect" in robust statistics. This
+script measures whether that mechanism is real on THIS project's actual price
+data, and quantifies it two ways:
+
+  PART 1 -- "As shipped" gap on real data.
+      The production historical_prices dict is NOT a rolling window -- it is a
+      single STATIC (median, std) constant per commodity, hand-set in
+      sample_data/historical_price_stats.csv (mirrored into db/schema.sql's
+      historical_prices table). This part runs the ACTUAL shipped function,
+      detect_price_anomaly(), against every real observed price in
+      sample_data/price_history/*.csv using the ACTUAL shipped static
+      constants, and compares the flag set against the already-validated
+      S-H-ESD persistent-anomaly set (ground truth for "this was a real
+      event"). Reports recall (of genuine persistent anomalies, how many does
+      the static 3-sigma catch) and precision-adjacent flag volume.
+
+  PART 2 -- Masking mechanism, isolated, on real price levels.
+      Simulates the scenario the code's OWN docstrings claim ("historical_prices:
+      dict commodity_code -> (median, std) 30-day rolling", engine.py:352,370)
+      but the shipped loaders never actually implement: a rolling 30-day window
+      recomputed from real data. Calls the ACTUAL detect_price_anomaly()
+      function (not a re-implementation) with median/std computed from a
+      window seeded with real cabai_rawit/beras_medium price levels, sweeping
+      the number of contaminating outliers already present in that window
+      (0..~40% of the window), and reports at what contamination fraction the
+      REAL genuine spike stops being flagged. Cross-checked against the
+      MAD-based rule (median +/- k*1.4826*MAD, same k=3.0) at every
+      contamination level.
+
+Both parts are seeded (--seed, default 2026) for reproducibility.
+
+Usage:
+    python benchmarks/anomaly_detector_gap.py
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import random
+import statistics
+import sys
+from datetime import datetime
+from typing import Dict, List, Tuple
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except (AttributeError, OSError):
+        pass
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)
+
+from matching_engine.engine import PRICE_ANOMALY_SIGMA, detect_price_anomaly
+from matching_engine.models import Commodity, DemandNode, Kabupaten, Tier
+from analysis.price_anomaly import CITY_NAMES, load_series, scan_all
+
+DEFAULT_SEED = 2026
+PRICE_HISTORY_DIR = os.path.join(ROOT, "sample_data", "price_history")
+HISTORICAL_STATS_CSV = os.path.join(ROOT, "sample_data", "historical_price_stats.csv")
+
+
+def load_static_stats() -> Dict[str, Tuple[float, float, str]]:
+    """Read the ACTUAL shipped static (median, std, source) per commodity."""
+    out = {}
+    with open(HISTORICAL_STATS_CSV, encoding="utf-8") as fh:
+        import csv
+        for row in csv.DictReader(fh):
+            out[row["commodity_code"]] = (
+                float(row["median_idr_per_kg"]),
+                float(row["std_idr_per_kg"]),
+                row["source"],
+            )
+    return out
+
+
+def _dummy_node(price: float):
+    """
+    Minimal SupplyNode-like stand-in: detect_price_anomaly only reads
+    node.price_per_kg, so a lightweight namespace avoids constructing full
+    Kabupaten/Commodity graphs for a million-point scan.
+    """
+    class _N:
+        pass
+    n = _N()
+    n.price_per_kg = price
+    return n
+
+
+# =============================================================================
+# PART 1 — "AS SHIPPED": static constants vs real observed prices
+# =============================================================================
+
+def run_as_shipped_gap(seed: int) -> None:
+    print("=" * 82)
+    print("  PART 1 — 'As shipped': static (median, std) vs real PIHPS Jatim prices")
+    print("=" * 82)
+    print(f"  historical_price_stats.csv is a STATIC constant per commodity "
+          f"(not a rolling window,\n  despite engine.py's docstring claiming "
+          f"'30-day rolling') -- this reproduces exactly what\n  production does "
+          f"today: detect_price_anomaly() called with the SAME fixed (median, std)\n"
+          f"  against every real observed price.\n")
+
+    static_stats = load_static_stats()
+    ground_truth = scan_all(PRICE_HISTORY_DIR, window=30, k=3.0, persist=2)
+    ground_truth_persistent = [a for a in ground_truth if a["persistent"]]
+
+    header = (f"  {'commodity':<15}{'source':<38}{'n_obs':>8}{'static_3σ_flags':>17}"
+              f"{'MAD_persistent':>16}{'overlap':>9}{'recall':>9}")
+    print(header)
+    print("  " + "-" * (len(header) - 2))
+
+    total_obs = 0
+    total_static_flags = 0
+    total_mad_persistent = 0
+    total_overlap = 0
+
+    for commodity, (median, std, source) in sorted(static_stats.items()):
+        gt_comm = [a for a in ground_truth_persistent if a["commodity_code"] == commodity]
+        if not gt_comm and not any(True for _ in []):
+            pass  # commodity may still have price series even with 0 persistent anomalies
+
+        n_obs = 0
+        static_flag_dates = set()  # (city_id, date)
+        for city_id in CITY_NAMES:
+            series = load_series(commodity, city_id, PRICE_HISTORY_DIR)
+            if not series:
+                continue
+            for date, price in series:
+                n_obs += 1
+                if detect_price_anomaly(_dummy_node(price), median, std):
+                    static_flag_dates.add((city_id, date))
+
+        if n_obs == 0:
+            continue  # commodity has no real price series (e.g. cabai_merah, tomat, ...)
+
+        gt_dates = {(a["city_id"], a["date"]) for a in gt_comm}
+        overlap = static_flag_dates & gt_dates
+        recall = (len(overlap) / len(gt_dates) * 100.0) if gt_dates else float("nan")
+
+        total_obs += n_obs
+        total_static_flags += len(static_flag_dates)
+        total_mad_persistent += len(gt_dates)
+        total_overlap += len(overlap)
+
+        recall_str = f"{recall:5.1f}%" if gt_dates else "n/a"
+        print(f"  {commodity:<15}{source:<38}{n_obs:>8}{len(static_flag_dates):>17}"
+              f"{len(gt_dates):>16}{len(overlap):>9}{recall_str:>9}")
+
+    print()
+    overall_recall = (total_overlap / total_mad_persistent * 100.0) if total_mad_persistent else 0.0
+    print(f"  TOTAL: {total_obs} real observations across 7 commodities x 8 IHK cities.")
+    print(f"  Static 3σ flagged {total_static_flags} points total.")
+    print(f"  S-H-ESD (robust, validated) flagged {total_mad_persistent} PERSISTENT genuine events.")
+    print(f"  Static 3σ caught {total_overlap}/{total_mad_persistent} of those "
+          f"({overall_recall:.1f}% recall) on the SAME date+city.")
+    print(f"\n  Caveat: telur_ayam and daging_ayam static constants are labelled "
+          f"'SYNTHETIC' in\n  historical_price_stats.csv (never calibrated against "
+          f"the real PIHPS series at all) --\n  their recall numbers reflect a "
+          f"made-up threshold, not a stale-but-real one.\n")
+
+
+# =============================================================================
+# PART 2 — Masking mechanism, isolated, on real price levels
+# =============================================================================
+
+def run_masking_mechanism(seed: int, window: int = 30, trials: int = 200) -> None:
+    print("=" * 82)
+    print("  PART 2 — Masking mechanism (rolling window, real price levels)")
+    print("=" * 82)
+    print(f"  Simulates the 'rolling {window}-day' design the docstring promises "
+          f"(engine.py:352)\n  but the shipped loader never implements. Calls the "
+          f"ACTUAL detect_price_anomaly()\n  function with median/std computed "
+          f"from a window built on REAL median price levels\n  (not an arbitrary "
+          f"Rp30,000 placeholder), sweeping how many contaminating outliers\n"
+          f"  are already sitting in that window when a genuine 3x spike arrives.\n")
+
+    # Real median price levels, PIHPS Jatim (Surabaya, 3578), for grounding.
+    scenarios = [
+        ("cabai_rawit (volatile, MAPE 23.2% per forecasting validation)", 41_000.0),
+        ("beras_medium (low-volatility staple)", 14_000.0),
+    ]
+
+    for label, base_price in scenarios:
+        print(f"  --- {label}: base price Rp{base_price:,.0f}/kg ---")
+        header = (f"  {'contam_n':>9}{'contam_%':>10}{'mean_std':>12}"
+                  f"{'3σ_flags_spike':>16}{'MAD_flags_spike':>17}")
+        print(header)
+
+        for contam_n in range(0, int(window * 0.5) + 1, 2):
+            contam_frac = contam_n / window * 100.0
+            rng = random.Random(seed + contam_n)
+            spike3sigma_hits = 0
+            mad_hits = 0
+            stds = []
+
+            for _ in range(trials):
+                # Build a window of `window` observations: base price with mild
+                # noise, `contam_n` of them replaced by contaminating spikes
+                # (2-3x base, random sign/magnitude), and ONE genuine test spike
+                # (3x base) at a fixed slot -- this is the point we ask both
+                # detectors to catch.
+                win = [base_price * rng.gauss(1.0, 0.03) for _ in range(window)]
+                contam_positions = rng.sample(range(window - 1), k=min(contam_n, window - 1))
+                for p in contam_positions:
+                    mult = rng.uniform(2.0, 3.0) * rng.choice([1, -0.4])
+                    win[p] = max(1.0, base_price * abs(mult))
+                test_spike_price = base_price * 3.0
+                win[-1] = test_spike_price  # genuine anomaly under test
+
+                median = statistics.median(win)
+                std = statistics.pstdev(win)
+                stds.append(std)
+
+                # ACTUAL shipped function — not a re-implementation.
+                if detect_price_anomaly(_dummy_node(test_spike_price), median, std):
+                    spike3sigma_hits += 1
+
+                # MAD-equivalent at the SAME k, matching analysis/price_anomaly's
+                # spread estimator (robust) instead of engine.py's std (non-robust).
+                abs_devs = [abs(x - median) for x in win]
+                mad = statistics.median(abs_devs)
+                if mad > 0:
+                    mad_z = abs(test_spike_price - median) / (1.4826 * mad)
+                    if mad_z > PRICE_ANOMALY_SIGMA:
+                        mad_hits += 1
+                else:
+                    mad_hits += 1  # flat window + spike -> trivially anomalous
+
+            mean_std = statistics.mean(stds)
+            print(f"  {contam_n:>9}{contam_frac:>9.1f}%{mean_std:>12,.0f}"
+                  f"{spike3sigma_hits:>10}/{trials:<5}{mad_hits:>10}/{trials:<5}")
+        print()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Quantify the gap between engine.py's z-score detector and "
+                     "analysis/price_anomaly's MAD detector, on AgriFlow's own real data.",
+    )
+    parser.add_argument("--seed", type=int, default=DEFAULT_SEED)
+    parser.add_argument("--trials", type=int, default=200)
+    args = parser.parse_args()
+
+    print(f"AgriFlow — Anomaly Detector Gap Analysis  (seed={args.seed})")
+    print(f"Run: {datetime.now().isoformat(timespec='seconds')}\n")
+
+    run_as_shipped_gap(args.seed)
+    run_masking_mechanism(args.seed, trials=args.trials)
+
+
+if __name__ == "__main__":
+    main()

benchmarks/dashboard_load.py

@@ -0,0 +1,129 @@
+"""
+Concurrency load test for the authenticated dashboard API.
+
+Answers one question with numbers rather than adjectives: how many simultaneous
+signed-in dashboard users can one API worker serve?
+
+Simulates N distinct users, each with their own signed JWT, hitting the
+endpoints the dashboard actually calls on page load. Reports throughput and
+latency percentiles, and verifies every response was correct — a fast server
+that returns 500s is not a passing result.
+
+Run:
+    python benchmarks/dashboard_load.py               # default 1000 users
+    python benchmarks/dashboard_load.py --users 5000 --workers 64
+
+Runs fully in-process against the ASGI app via TestClient, so it measures
+application cost with no network or TLS in the way. Real-world numbers will be
+lower; this isolates whether *our code* is the bottleneck.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import statistics
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timedelta, timezone
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+SECRET = "load-test-secret-not-used-in-production"
+
+
+def make_token(user_index: int) -> str:
+    import jwt
+    now = datetime.now(timezone.utc)
+    return jwt.encode(
+        {
+            "sub": f"00000000-0000-0000-0000-{user_index:012d}",
+            "email": f"user{user_index}@dinas.example.go.id",
+            "aud": "authenticated", "role": "authenticated",
+            "iat": now, "exp": now + timedelta(hours=1),
+        },
+        SECRET, algorithm="HS256",
+    )
+
+
+# The requests a dashboard makes when a signed-in user opens it.
+PAGE_LOAD = [
+    ("/api/v1/commodities", {}),
+    ("/api/v1/kabupaten", {}),
+    ("/api/v1/surplus-deficit", {"commodity": "beras_premium"}),
+    ("/api/v1/matches", {"commodity": "beras_premium", "limit": 50}),
+    ("/api/v1/anomalies", {"limit": 20}),
+]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--users", type=int, default=1000)
+    ap.add_argument("--workers", type=int, default=32)
+    args = ap.parse_args()
+
+    os.environ["SUPABASE_JWT_SECRET"] = SECRET
+    os.environ.pop("SUPABASE_URL", None)
+    os.environ["REQUIRE_AUTH"] = "true"      # every request must verify a token
+    os.environ["PHONE_HASH_SALT"] = "load-test"
+
+    from fastapi.testclient import TestClient
+    from whatsapp_bot import server
+
+    print(f"Minting {args.users:,} distinct user tokens…")
+    tokens = [make_token(i) for i in range(args.users)]
+
+    latencies: list[float] = []
+    failures: list[str] = []
+
+    with TestClient(server.app) as client:
+        # Warm the caches so we measure steady state, not cold start.
+        for path, params in PAGE_LOAD:
+            client.get(path, params=params, headers={"Authorization": f"Bearer {tokens[0]}"})
+
+        def one_user(token: str) -> float:
+            t0 = time.perf_counter()
+            for path, params in PAGE_LOAD:
+                r = client.get(path, params=params,
+                               headers={"Authorization": f"Bearer {token}"})
+                if r.status_code != 200:
+                    failures.append(f"{path} -> {r.status_code}")
+            return (time.perf_counter() - t0) * 1000
+
+        print(f"Running {args.users:,} user sessions across {args.workers} workers…")
+        t_start = time.perf_counter()
+        with ThreadPoolExecutor(max_workers=args.workers) as pool:
+            latencies = list(pool.map(one_user, tokens))
+        elapsed = time.perf_counter() - t_start
+
+    latencies.sort()
+
+    def pct(p: float) -> float:
+        return latencies[min(int(len(latencies) * p), len(latencies) - 1)]
+
+    requests = args.users * len(PAGE_LOAD)
+    print()
+    print("=" * 62)
+    print(f"  users simulated      {args.users:,}")
+    print(f"  requests issued      {requests:,}  ({len(PAGE_LOAD)} per user)")
+    print(f"  wall clock           {elapsed:.2f} s")
+    print(f"  throughput           {requests / elapsed:,.0f} req/s")
+    print(f"  user sessions/sec    {args.users / elapsed:,.0f}")
+    print("-" * 62)
+    print(f"  full page load  mean {statistics.mean(latencies):7.1f} ms")
+    print(f"                  p50  {pct(0.50):7.1f} ms")
+    print(f"                  p95  {pct(0.95):7.1f} ms")
+    print(f"                  p99  {pct(0.99):7.1f} ms")
+    print(f"                  max  {latencies[-1]:7.1f} ms")
+    print("-" * 62)
+    print(f"  failed requests      {len(failures)}")
+    if failures:
+        for f in sorted(set(failures))[:5]:
+            print(f"    {f}  (x{failures.count(f)})")
+    print("=" * 62)
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

benchmarks/equity_comparison.py

@@ -0,0 +1,617 @@
+"""
+benchmarks/equity_comparison.py — Baseline Comparison + Equity Sensitivity Harness.
+
+Action 2 (baseline comparison) + Action 6 (sensitivity) from recommendation.md.
+Generates two pitch tables and writes them to benchmarks/output/equity_comparison.md.
+
+Five strategies:
+    1. pure_greedy       — equity_fn=lambda _: 1.0, force_strategy="greedy"
+                           Efficiency anchor (honest frontier: no equity).
+    2. agriflow          — default equity_fn + default dispatch
+                           Production behavior.
+    3. uniform           — equal split per surplus across viable deficits
+                           Equity anchor (ignores score entirely).
+    4. proportional      — allocation proportional to deficit magnitude per kab
+                           Status-quo Bapanas foil (attack #7 answer).
+    5. agriflow_smoothed — linear-interpolation closure over existing tier knots
+                           (1.30/1.15/1.05/1.00 at IPM 68/72/78), no new params.
+                           Demonstrates smoothed ≈ step (attack #2 answer).
+
+All five strategies receive IDENTICAL inputs: same supply/deficit pool, same
+logistics context, same hard constraints (generate_candidates). Only
+scoring/prioritisation differs. This is the apple-to-apple requirement.
+
+Run:
+    python benchmarks/equity_comparison.py
+"""
+from __future__ import annotations
+import os
+import sys
+from collections import defaultdict
+from typing import Dict, List, Tuple
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except (AttributeError, OSError):
+        pass
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from matching_engine import run_matching
+from matching_engine.allocation import equity_multiplier_value
+from matching_engine.constraints import generate_candidates
+from matching_engine.models import LogisticsContext
+from sample_data.loader import load_all_sample_data
+
+from benchmarks._metrics import (
+    atkinson,
+    fulfillment_by_node,
+    gini,
+    kab_fulfillment,
+    min_fulfillment,
+    total_deficit_covered,
+)
+
+# ---------------------------------------------------------------------------
+# Key type: (kab_id, commodity_code, segment_value) -> float
+# ---------------------------------------------------------------------------
+_Key = Tuple[str, str, str]
+
+SAMPANG_ID = "3527"
+BANGKALAN_ID = "3526"
+
+
+# ---------------------------------------------------------------------------
+# HELPER: extract demand_tons dict from loaded deficit nodes
+# ---------------------------------------------------------------------------
+
+def _build_demand_tons(deficit_nodes) -> Dict[_Key, float]:
+    """Build demand_tons dict from a list of DemandNode objects."""
+    out: Dict[_Key, float] = {}
+    for d in deficit_nodes:
+        key = (d.kabupaten.id, d.commodity.code, d.segment.value)
+        out[key] = out.get(key, 0.0) + d.volume_tons
+    return out
+
+
+# ---------------------------------------------------------------------------
+# HELPER: extract matched_tons dict from a MatchingReport
+# ---------------------------------------------------------------------------
+
+def _report_to_matched_tons(report) -> Dict[_Key, float]:
+    """Adapt MatchingReport.matches -> matched_tons dict."""
+    out: Dict[_Key, float] = {}
+    for m in report.matches:
+        key = (m.deficit.kabupaten.id, m.deficit.commodity.code, m.deficit.segment.value)
+        out[key] = out.get(key, 0.0) + m.matched_volume_tons
+    return out
+
+
+# ---------------------------------------------------------------------------
+# STRATEGY 3: UNIFORM ALLOCATION
+# Uses only Layer 1 candidate generation; ignores score entirely.
+# Each surplus splits its volume equally across its viable deficits,
+# capping at each deficit's actual need.
+# ---------------------------------------------------------------------------
+
+def uniform_allocate(surplus, deficit, logistics) -> Dict[_Key, float]:
+    """
+    Equity baseline: each surplus splits volume equally across its viable
+    deficit partners (post hard-constraint). Score is ignored entirely.
+
+    Returns matched_tons dict: (kab_id, commodity_code, segment) -> tons matched.
+    This is a foil only — not a product feature, implemented in benchmarks/.
+    """
+    candidates = generate_candidates(surplus, deficit, logistics=logistics)
+
+    # Group: surplus_key -> list of deficit nodes that can receive it
+    surplus_to_deficits: Dict[str, List] = defaultdict(list)
+    for s, d in candidates:
+        s_key = s.kabupaten.id + "_" + s.commodity.code
+        surplus_to_deficits[s_key].append((s, d))
+
+    # Build demand lookup: (kab_id, commodity, segment) -> total_demand
+    demand_lookup: Dict[_Key, float] = _build_demand_tons(deficit)
+
+    # remaining demand per key
+    remaining_demand: Dict[_Key, float] = dict(demand_lookup)
+    matched: Dict[_Key, float] = defaultdict(float)
+
+    # For each surplus, distribute its volume equally across eligible deficits
+    # Iterate multiple passes to handle partial fills (demand may already be
+    # partially filled from another surplus). Simple single-pass equal split:
+    # divide surplus volume by number of eligible deficit keys.
+    for s_key, pairs in surplus_to_deficits.items():
+        s = pairs[0][0]
+        remaining_supply = s.volume_tons
+        eligible = [
+            (s_, d) for s_, d in pairs
+            if remaining_demand.get(
+                (d.kabupaten.id, d.commodity.code, d.segment.value), 0.0
+            ) > 0
+        ]
+        if not eligible:
+            continue
+        n = len(eligible)
+        share = remaining_supply / n  # equal share per eligible deficit
+        for _, d in eligible:
+            d_key = (d.kabupaten.id, d.commodity.code, d.segment.value)
+            allocation = min(share, remaining_demand.get(d_key, 0.0))
+            matched[d_key] += allocation
+            remaining_demand[d_key] = max(0.0, remaining_demand[d_key] - allocation)
+
+    return dict(matched)
+
+
+# ---------------------------------------------------------------------------
+# STRATEGY 4: PROPORTIONAL-TO-DEFICIT (Bapanas status-quo foil)
+# Allocates each surplus proportionally to the deficit magnitude of each
+# eligible kab. Larger deficit gets larger share.
+# ---------------------------------------------------------------------------
+
+def proportional_allocate(surplus, deficit, logistics) -> Dict[_Key, float]:
+    """
+    Status-quo Bapanas foil: allocation proportional to deficit magnitude.
+
+    Each surplus distributes volume to eligible deficits weighted by
+    their remaining demand volume. Ignores score, distance ranking, equity.
+    Represents a simple pro-rata rule: 'give more to those who need more'.
+
+    Returns matched_tons dict: (kab_id, commodity_code, segment) -> tons.
+    """
+    candidates = generate_candidates(surplus, deficit, logistics=logistics)
+
+    surplus_to_deficits: Dict[str, List] = defaultdict(list)
+    for s, d in candidates:
+        s_key = s.kabupaten.id + "_" + s.commodity.code
+        surplus_to_deficits[s_key].append((s, d))
+
+    demand_lookup: Dict[_Key, float] = _build_demand_tons(deficit)
+    remaining_demand: Dict[_Key, float] = dict(demand_lookup)
+    matched: Dict[_Key, float] = defaultdict(float)
+
+    for s_key, pairs in surplus_to_deficits.items():
+        s = pairs[0][0]
+        remaining_supply = s.volume_tons
+        eligible = [
+            (s_, d) for s_, d in pairs
+            if remaining_demand.get(
+                (d.kabupaten.id, d.commodity.code, d.segment.value), 0.0
+            ) > 0
+        ]
+        if not eligible:
+            continue
+        # Weight = remaining demand magnitude
+        d_keys = [
+            (d.kabupaten.id, d.commodity.code, d.segment.value)
+            for _, d in eligible
+        ]
+        weights = [remaining_demand[k] for k in d_keys]
+        total_weight = sum(weights)
+        if total_weight == 0:
+            continue
+        for d_key, w in zip(d_keys, weights):
+            share = remaining_supply * (w / total_weight)
+            allocation = min(share, remaining_demand[d_key])
+            matched[d_key] += allocation
+            remaining_demand[d_key] = max(0.0, remaining_demand[d_key] - allocation)
+
+    return dict(matched)
+
+
+# ---------------------------------------------------------------------------
+# STRATEGY 5: AGRIFLOW-SMOOTHED (linear interpolation over existing knots)
+# This is a closure ONLY — do not modify equity_multiplier_value production.
+# Knots: (68, 1.30), (72, 1.15), (78, 1.05), (inf, 1.00)
+# Linear interpolation between knots; outside range uses boundary values.
+# ---------------------------------------------------------------------------
+
+def _equity_smoothed(ipm: float) -> float:
+    """
+    Linear interpolation over the existing tier knots.
+    Knot values match equity_multiplier_value exactly at knot boundaries:
+        IPM=68 -> 1.30, IPM=72 -> 1.15, IPM=78 -> 1.05, IPM>=85 -> 1.00
+
+    Below 68: returns 1.30 (same as step-function).
+    Between knots: linear interpolation.
+    Above 85: returns 1.00.
+
+    This demonstrates that smoothed behaviour approximates the step-function
+    (attack #2 answer) without changing any production code.
+    """
+    # Knot points: (ipm, multiplier)
+    knots = [(68.0, 1.30), (72.0, 1.15), (78.0, 1.05), (85.0, 1.00)]
+    if ipm <= knots[0][0]:
+        return knots[0][1]
+    if ipm >= knots[-1][0]:
+        return knots[-1][1]
+    for i in range(len(knots) - 1):
+        x0, y0 = knots[i]
+        x1, y1 = knots[i + 1]
+        if x0 <= ipm <= x1:
+            t = (ipm - x0) / (x1 - x0)
+            return y0 + t * (y1 - y0)
+    return 1.00  # unreachable
+
+
+# ---------------------------------------------------------------------------
+# ACTION 6 — SENSITIVITY: three threshold variants
+# ---------------------------------------------------------------------------
+
+def equity_strict(ipm: float) -> float:
+    """Strict thresholds: 1.50/1.25/1.10/1.00 at IPM <65/<70/<75/>=75."""
+    if ipm < 65:
+        return 1.50
+    elif ipm < 70:
+        return 1.25
+    elif ipm < 75:
+        return 1.10
+    else:
+        return 1.00
+
+
+def equity_current(ipm: float) -> float:
+    """Current (production) thresholds — delegates to equity_multiplier_value.
+    Single source of truth: this column in the sensitivity table IS the
+    shipped behavior, not a re-typed copy that could drift."""
+    return equity_multiplier_value(ipm)
+
+
+def equity_lenient(ipm: float) -> float:
+    """Lenient thresholds: 1.15/1.08/1.03/1.00 at IPM <70/<75/<80/>=80."""
+    if ipm < 70:
+        return 1.15
+    elif ipm < 75:
+        return 1.08
+    elif ipm < 80:
+        return 1.03
+    else:
+        return 1.00
+
+
+# ---------------------------------------------------------------------------
+# BOUNDARY PERTURBATION — how many Jatim kabs change tier under ±1/±2 shifts
+# ---------------------------------------------------------------------------
+
+def boundary_perturbation(kabupaten_dict: dict) -> dict:
+    """
+    Shift each IPM threshold by ±1 and ±2 points and count how many
+    Jatim kabupaten change tier (i.e. receive a different multiplier).
+
+    Thresholds being perturbed: 68, 72, 78 (the three break points in
+    equity_multiplier_value for Jatim 2024).
+
+    Returns a dict with counts per shift magnitude for each threshold.
+    """
+    ipm_values = [k.ipm for k in kabupaten_dict.values()]
+
+    def count_different(delta: float) -> int:
+        """Count kabs whose multiplier changes when ALL thresholds shift by delta."""
+        changed = 0
+        for ipm in ipm_values:
+            orig = equity_multiplier_value(ipm)
+            # Shifted function: thresholds 68->68+delta, 72->72+delta, 78->78+delta
+            t68 = 68.0 + delta
+            t72 = 72.0 + delta
+            t78 = 78.0 + delta
+            if ipm < t68:
+                shifted = 1.30
+            elif ipm < t72:
+                shifted = 1.15
+            elif ipm < t78:
+                shifted = 1.05
+            else:
+                shifted = 1.00
+            if abs(orig - shifted) > 1e-9:
+                changed += 1
+        return changed
+
+    result = {}
+    for delta in (-2.0, -1.0, +1.0, +2.0):
+        result[delta] = count_different(delta)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# COMPUTE METRICS ROW for a strategy
+# ---------------------------------------------------------------------------
+
+def compute_row(
+    strategy_name: str,
+    matched_tons: Dict[_Key, float],
+    demand_tons: Dict[_Key, float],
+) -> dict:
+    """Compute all 5 metric columns for one strategy."""
+    return {
+        "strategy": strategy_name,
+        "total_deficit_covered": total_deficit_covered(matched_tons, demand_tons),
+        "gini": gini(matched_tons, demand_tons),
+        "atkinson_05": atkinson(matched_tons, demand_tons, epsilon=0.5),
+        "atkinson_10": atkinson(matched_tons, demand_tons, epsilon=1.0),
+        "min_fulfillment": min_fulfillment(matched_tons, demand_tons),
+        "sampang": kab_fulfillment(matched_tons, demand_tons, SAMPANG_ID),
+        "bangkalan": kab_fulfillment(matched_tons, demand_tons, BANGKALAN_ID),
+    }
+
+
+# ---------------------------------------------------------------------------
+# MAIN
+# ---------------------------------------------------------------------------
+
+def main():
+    print("=" * 80)
+    print("  AGRIFLOW EQUITY COMPARISON HARNESS")
+    print("=" * 80)
+    print("  Loading Jatim sample data ...")
+
+    data = load_all_sample_data()
+    surplus = data["surplus"]
+    deficit = data["deficit"]
+    weather = data["weather"]
+    historical = data["historical_prices"]
+    kabupaten_dict = data["kabupaten"]
+    logistics = LogisticsContext()
+
+    demand_tons = _build_demand_tons(deficit)
+
+    print(f"  Surplus nodes: {len(surplus)}")
+    print(f"  Deficit nodes: {len(deficit)}")
+    print(f"  Demand keys:   {len(demand_tons)}")
+    print()
+
+    # -----------------------------------------------------------------------
+    # RUN FIVE STRATEGIES
+    # All use same surplus/deficit/logistics — only equity_fn / prioritisation differs
+    # -----------------------------------------------------------------------
+
+    print("  Running strategies ...")
+
+    # 1. Pure greedy — efficiency anchor
+    report_greedy = run_matching(
+        surplus, deficit,
+        logistics=logistics,
+        weather_forecasts=weather,
+        historical_prices=historical,
+        force_strategy="greedy",
+        equity_fn=lambda _ipm: 1.0,
+    )
+    matched_greedy = _report_to_matched_tons(report_greedy)
+    print("    [1/5] pure_greedy done")
+
+    # 2. AgriFlow — default (production behavior, equity_fn omitted)
+    report_agriflow = run_matching(
+        surplus, deficit,
+        logistics=logistics,
+        weather_forecasts=weather,
+        historical_prices=historical,
+    )
+    matched_agriflow = _report_to_matched_tons(report_agriflow)
+    print("    [2/5] agriflow done")
+
+    # 3. Uniform — equity anchor (ignores score, equal split)
+    matched_uniform = uniform_allocate(surplus, deficit, logistics)
+    print("    [3/5] uniform done")
+
+    # 4. Proportional-to-deficit (Bapanas status-quo foil)
+    matched_proportional = proportional_allocate(surplus, deficit, logistics)
+    print("    [4/5] proportional done")
+
+    # 5. AgriFlow-smoothed — linear interpolation over existing knots
+    report_smoothed = run_matching(
+        surplus, deficit,
+        logistics=logistics,
+        weather_forecasts=weather,
+        historical_prices=historical,
+        equity_fn=_equity_smoothed,
+    )
+    matched_smoothed = _report_to_matched_tons(report_smoothed)
+    print("    [5/5] agriflow_smoothed done")
+    print()
+
+    # -----------------------------------------------------------------------
+    # TABLE 1 — BASELINE COMPARISON (5 strategies × 5 metrics + kab spotlight)
+    # -----------------------------------------------------------------------
+
+    rows = [
+        compute_row("pure_greedy",       matched_greedy,       demand_tons),
+        compute_row("agriflow",          matched_agriflow,     demand_tons),
+        compute_row("uniform",           matched_uniform,      demand_tons),
+        compute_row("proportional",      matched_proportional, demand_tons),
+        compute_row("agriflow_smoothed", matched_smoothed,     demand_tons),
+    ]
+
+    table1_header = (
+        "| Strategy          | Coverage | Gini  | Atk(0.5) | Atk(1.0) | "
+        "MinFulfill | Sampang | Bangkalan |"
+    )
+    table1_sep = (
+        "|-------------------|----------|-------|----------|----------|"
+        "-----------|---------|-----------|"
+    )
+    table1_lines = [table1_header, table1_sep]
+    for r in rows:
+        line = (
+            f"| {r['strategy']:<17s} "
+            f"| {r['total_deficit_covered']:.4f}   "
+            f"| {r['gini']:.4f}"
+            f"| {r['atkinson_05']:.4f}   "
+            f"| {r['atkinson_10']:.4f}   "
+            f"| {r['min_fulfillment']:.4f}    "
+            f"| {r['sampang']:.4f} "
+            f"| {r['bangkalan']:.4f}    |"
+        )
+        table1_lines.append(line)
+
+    print("=" * 80)
+    print("  TABLE 1 — BASELINE COMPARISON (5 strategies)")
+    print("  Coverage = volume-weighted tons fulfilled / tons demanded")
+    print("  Gini / Atkinson = weighted by demand volume (lower = more equitable)")
+    print("  MinFulfill = fulfillment ratio of worst-served demand node (higher = better)")
+    print("  Sampang=3527 (IPM 66.72), Bangkalan=3526 (IPM 67.70)")
+    print("=" * 80)
+    for line in table1_lines:
+        print(line)
+    print()
+
+    # -----------------------------------------------------------------------
+    # ACTION 6 — SENSITIVITY (strict / current / lenient threshold variants)
+    # -----------------------------------------------------------------------
+
+    print("  Running Action 6 sensitivity ...")
+
+    sens_variants = [
+        ("strict",  equity_strict,   "IPM <65→1.50, <70→1.25, <75→1.10, >=75→1.00"),
+        ("current", equity_current,  "IPM <68→1.30, <72→1.15, <78→1.05, >=78→1.00 [PROD]"),
+        ("lenient", equity_lenient,  "IPM <70→1.15, <75→1.08, <80→1.03, >=80→1.00"),
+    ]
+
+    sens_rows = []
+    for name, fn, desc in sens_variants:
+        rep = run_matching(
+            surplus, deficit,
+            logistics=logistics,
+            weather_forecasts=weather,
+            historical_prices=historical,
+            equity_fn=fn,
+        )
+        mt = _report_to_matched_tons(rep)
+        sens_rows.append({
+            "variant": name,
+            "desc": desc,
+            "total_deficit_covered": total_deficit_covered(mt, demand_tons),
+            "gini": gini(mt, demand_tons),
+            "sampang": kab_fulfillment(mt, demand_tons, SAMPANG_ID),
+            "bangkalan": kab_fulfillment(mt, demand_tons, BANGKALAN_ID),
+        })
+
+    table2_header = (
+        "| Variant | Coverage | Gini  | Sampang | Bangkalan | Description |"
+    )
+    table2_sep = (
+        "|---------|----------|-------|---------|-----------|-------------|"
+    )
+    table2_lines = [table2_header, table2_sep]
+    for r in sens_rows:
+        line = (
+            f"| {r['variant']:<7s} "
+            f"| {r['total_deficit_covered']:.4f}   "
+            f"| {r['gini']:.4f}"
+            f"| {r['sampang']:.4f} "
+            f"| {r['bangkalan']:.4f}    "
+            f"| {r['desc']} |"
+        )
+        table2_lines.append(line)
+
+    print()
+    print("=" * 80)
+    print("  TABLE 2 — ACTION 6 SENSITIVITY (threshold variants)")
+    print("  'current' delegates to equity_multiplier_value — single source of truth.")
+    print("=" * 80)
+    for line in table2_lines:
+        print(line)
+    print()
+
+    # -----------------------------------------------------------------------
+    # BOUNDARY PERTURBATION
+    # -----------------------------------------------------------------------
+
+    perturb = boundary_perturbation(kabupaten_dict)
+    print("=" * 80)
+    print("  BOUNDARY PERTURBATION — kabs changing tier when thresholds shift ±1/±2")
+    print("  (Attack #2: 'cliff effect' — how sensitive is tier assignment to threshold?)")
+    print("=" * 80)
+    print("  Jatim IPM values (sorted):")
+    ipm_sorted = sorted(k.ipm for k in kabupaten_dict.values())
+    print("    " + "  ".join(f"{v:.2f}" for v in ipm_sorted))
+    print()
+    print("  | Threshold shift | Kabs changing tier |")
+    print("  |-----------------|---------------------|")
+    for delta in (-2.0, -1.0, +1.0, +2.0):
+        label = f"{delta:+.0f} pts"
+        print(f"  | {label:<15s} | {perturb[delta]:2d}                  |")
+    print()
+    print("  Interpretation:")
+    print("  - 0-1 kabs per ±1pt shift = cliff effect negligible.")
+    print("  - More kabs = higher sensitivity (attack #2 stronger).")
+    print()
+
+    # -----------------------------------------------------------------------
+    # WRITE OUTPUT
+    # -----------------------------------------------------------------------
+
+    output_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "output")
+    os.makedirs(output_dir, exist_ok=True)
+    output_path = os.path.join(output_dir, "equity_comparison.md")
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write("# AgriFlow Equity Comparison\n\n")
+        f.write("Generated by `benchmarks/equity_comparison.py`.\n\n")
+        f.write("## Table 1 — Baseline Comparison (5 strategies)\n\n")
+        f.write("Coverage = volume-weighted tons fulfilled / tons demanded.  \n")
+        f.write("Gini / Atkinson = weighted by demand volume; lower = more equitable.  \n")
+        f.write("MinFulfill = fulfillment ratio of worst-served demand node; higher = better.  \n")
+        f.write("Sampang=3527 (IPM 66.72), Bangkalan=3526 (IPM 67.70).  \n\n")
+        for line in table1_lines:
+            f.write(line + "\n")
+        f.write("\n")
+        f.write("## Table 2 — Action 6 Sensitivity (threshold variants)\n\n")
+        f.write("`current` delegates to `equity_multiplier_value` — single source of truth.\n\n")
+        for line in table2_lines:
+            f.write(line + "\n")
+        f.write("\n")
+        f.write("## Boundary Perturbation\n\n")
+        f.write("Shift all IPM thresholds simultaneously by ±1 or ±2 points.\n")
+        f.write("Counts kabupaten in Jatim (38 total) that move to a different tier.\n\n")
+        f.write("| Threshold shift | Kabs changing tier |\n")
+        f.write("|-----------------|---------------------|\n")
+        for delta in (-2.0, -1.0, +1.0, +2.0):
+            label = f"{delta:+.0f} pts"
+            f.write(f"| {label:<15s} | {perturb[delta]:2d}                  |\n")
+        f.write("\n")
+
+    print(f"  Tables written to: {output_path}")
+    print()
+
+    # -----------------------------------------------------------------------
+    # QUICK SANITY CHECK — report potential ordering violations
+    # -----------------------------------------------------------------------
+
+    greedy_cov = rows[0]["total_deficit_covered"]
+    agriflow_cov = rows[1]["total_deficit_covered"]
+    greedy_gini = rows[0]["gini"]
+    agriflow_gini = rows[1]["gini"]
+    uniform_gini = rows[2]["gini"]
+    sampang_agriflow = rows[1]["sampang"]
+    sampang_greedy = rows[0]["sampang"]
+
+    print("  ORDERING CHECKS (expected by pitch claims):")
+    check = lambda ok, msg: print(f"  {'PASS' if ok else 'FAIL'} {msg}")
+    check(greedy_cov >= agriflow_cov,
+          f"greedy coverage ({greedy_cov:.4f}) >= agriflow coverage ({agriflow_cov:.4f})")
+    check(agriflow_gini <= greedy_gini,
+          f"agriflow gini ({agriflow_gini:.4f}) <= greedy gini ({greedy_gini:.4f})")
+    check(uniform_gini <= agriflow_gini,
+          f"uniform gini ({uniform_gini:.4f}) <= agriflow gini ({agriflow_gini:.4f})")
+    check(sampang_agriflow >= sampang_greedy,
+          f"Sampang: agriflow ({sampang_agriflow:.4f}) >= greedy ({sampang_greedy:.4f})")
+    strict_sampang = sens_rows[0]["sampang"]
+    lenient_sampang = sens_rows[2]["sampang"]
+    check(strict_sampang >= lenient_sampang,
+          f"strict Sampang ({strict_sampang:.4f}) >= lenient Sampang ({lenient_sampang:.4f})")
+
+    smoothed_cov = rows[4]["total_deficit_covered"]
+    smoothed_gini = rows[4]["gini"]
+    check(abs(smoothed_cov - agriflow_cov) < 0.05,
+          f"smoothed coverage ({smoothed_cov:.4f}) approx agriflow ({agriflow_cov:.4f})")
+    check(abs(smoothed_gini - agriflow_gini) < 0.05,
+          f"smoothed gini ({smoothed_gini:.4f}) approx agriflow gini ({agriflow_gini:.4f})")
+    print()
+
+    print("=" * 80)
+    print("  DONE. Copy tables from benchmarks/output/equity_comparison.md into pitch deck.")
+    print("=" * 80)
+
+
+if __name__ == "__main__":
+    main()

benchmarks/equity_comparison_constrained.py

@@ -0,0 +1,484 @@
+"""
+benchmarks/equity_comparison_constrained.py — Side-by-side ABUNDANT vs CONSTRAINED.
+
+Skenario CONSTRAINED: La Nina banjir besar menghantam tiga sentra beras
+utama Jatim bagian barat — Ngawi (3521), Madiun (3519), Bojonegoro (3522) —
+secara bersamaan pada musim panen Oktober–November.
+
+Narasi (defensible):
+    Ngawi, Madiun, dan Bojonegoro adalah kabupaten di dataran rendah lembah
+    Bengawan Solo dan anak sungainya. Ketiga kab ini secara historis mengalami
+    banjir bersamaan selama fase La Nina intensitas tinggi (pola 2010, 2020–21,
+    2022–23). Dalam skenario ini, banjir menghanguskan atau memotong akses ke
+    6 surplus: beras_premium Bojonegoro (650t) + Ngawi (500t), beras_medium
+    Madiun (1200t) + Ngawi (900t), jagung Bojonegoro (800t) + Ngawi (600t).
+    Total supply yang hilang: 4.650 ton.
+
+Arithmetic:
+    ABUNDANT: surplus=8.612t, deficit=5.249t, ratio=1.641 (melimpah)
+    CONSTRAINED: surplus=3.962t, deficit=5.249t, ratio=0.754 (kekurangan 32.5%)
+
+Fixture:
+    sample_data/surplus_deficit_constrained.csv — hasil omit 6 baris SURPLUS
+    dari kab {3521, 3519, 3522}. Committed ke repo dengan fixed content.
+    JANGAN timpa surplus_deficit.csv yang lama.
+
+Mengapa BUKAN skenario rekayasa:
+    1. Ketiga kab bukan penghasil Sampang/Bangkalan — tidak ada konflik
+       kepentingan antara narasi dan hasil yang diharap.
+    2. Kelangkaan terjadi di beras & jagung (staple), bukan cabai — lebih
+       realistis sebagai krisis pangan.
+    3. Sampang dan Bangkalan tetap memiliki DEFISIT beras_premium yang besar
+       (200t dan 250t) tetapi tidak ada surplus dari kab shock yang semula
+       menutup mereka — supply yang tersisa harus diperebutkan.
+
+Run:
+    python benchmarks/equity_comparison_constrained.py
+"""
+from __future__ import annotations
+import os
+import sys
+from collections import defaultdict
+from typing import Dict, List, Tuple
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except (AttributeError, OSError):
+        pass
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from matching_engine import run_matching
+from matching_engine.allocation import equity_multiplier_value
+from matching_engine.constraints import generate_candidates
+from matching_engine.models import LogisticsContext
+from sample_data.loader import load_all_sample_data
+
+from benchmarks._metrics import (
+    atkinson,
+    fulfillment_by_node,
+    gini,
+    kab_fulfillment,
+    min_fulfillment,
+    total_deficit_covered,
+)
+from benchmarks.equity_comparison import (
+    _build_demand_tons,
+    _equity_smoothed,
+    _report_to_matched_tons,
+    boundary_perturbation,
+    compute_row,
+    equity_current,
+    equity_lenient,
+    equity_strict,
+    proportional_allocate,
+    uniform_allocate,
+    SAMPANG_ID,
+    BANGKALAN_ID,
+)
+
+# ---------------------------------------------------------------------------
+# Scenario metadata
+# ---------------------------------------------------------------------------
+
+CONSTRAINED_CSV = "surplus_deficit_constrained.csv"
+SHOCK_KABS = {
+    "3521": "Ngawi",
+    "3519": "Madiun",
+    "3522": "Bojonegoro",
+}
+CONSTRAINED_SURPLUS_TONS = 3962.0
+CONSTRAINED_DEFICIT_TONS = 5249.0
+
+
+def _run_five_strategies(surplus, deficit, logistics, weather, historical):
+    """Run all 5 strategies on the given supply/deficit pool.
+
+    Returns dict: strategy_name -> matched_tons dict.
+    """
+    # 1. Pure greedy
+    report_greedy = run_matching(
+        surplus, deficit,
+        logistics=logistics,
+        weather_forecasts=weather,
+        historical_prices=historical,
+        force_strategy="greedy",
+        equity_fn=lambda _ipm: 1.0,
+    )
+
+    # 2. AgriFlow default
+    report_agriflow = run_matching(
+        surplus, deficit,
+        logistics=logistics,
+        weather_forecasts=weather,
+        historical_prices=historical,
+    )
+
+    # 3. Uniform
+    matched_uniform = uniform_allocate(surplus, deficit, logistics)
+
+    # 4. Proportional
+    matched_proportional = proportional_allocate(surplus, deficit, logistics)
+
+    # 5. AgriFlow-smoothed
+    report_smoothed = run_matching(
+        surplus, deficit,
+        logistics=logistics,
+        weather_forecasts=weather,
+        historical_prices=historical,
+        equity_fn=_equity_smoothed,
+    )
+
+    return {
+        "pure_greedy":       _report_to_matched_tons(report_greedy),
+        "agriflow":          _report_to_matched_tons(report_agriflow),
+        "uniform":           matched_uniform,
+        "proportional":      matched_proportional,
+        "agriflow_smoothed": _report_to_matched_tons(report_smoothed),
+    }
+
+
+def _run_sensitivity(surplus, deficit, logistics, weather, historical, demand_tons):
+    """Run Action 6 sensitivity (strict/current/lenient) on a given pool."""
+    sens_variants = [
+        ("strict",  equity_strict,  "IPM <65->1.50, <70->1.25, <75->1.10, >=75->1.00"),
+        ("current", equity_current, "IPM <68->1.30, <72->1.15, <78->1.05, >=78->1.00 [PROD]"),
+        ("lenient", equity_lenient, "IPM <70->1.15, <75->1.08, <80->1.03, >=80->1.00"),
+    ]
+    rows = []
+    for name, fn, desc in sens_variants:
+        rep = run_matching(
+            surplus, deficit,
+            logistics=logistics,
+            weather_forecasts=weather,
+            historical_prices=historical,
+            equity_fn=fn,
+        )
+        mt = _report_to_matched_tons(rep)
+        rows.append({
+            "variant": name,
+            "desc": desc,
+            "total_deficit_covered": total_deficit_covered(mt, demand_tons),
+            "gini": gini(mt, demand_tons),
+            "sampang": kab_fulfillment(mt, demand_tons, SAMPANG_ID),
+            "bangkalan": kab_fulfillment(mt, demand_tons, BANGKALAN_ID),
+            "min_fulfillment": min_fulfillment(mt, demand_tons),
+        })
+    return rows
+
+
+def _format_table1(rows, demand_tons, caption=""):
+    """Format 5-strategy rows as Markdown table lines."""
+    lines = []
+    if caption:
+        lines.append(f"### {caption}")
+        lines.append("")
+    header = (
+        "| Strategy          | Coverage | Gini  | Atk(0.5) | Atk(1.0) | "
+        "MinFulfill | Sampang | Bangkalan |"
+    )
+    sep = (
+        "|-------------------|----------|-------|----------|----------|"
+        "-----------|---------|-----------|"
+    )
+    lines.append(header)
+    lines.append(sep)
+    for r in rows:
+        line = (
+            f"| {r['strategy']:<17s} "
+            f"| {r['total_deficit_covered']:.4f}   "
+            f"| {r['gini']:.4f}"
+            f"| {r['atkinson_05']:.4f}   "
+            f"| {r['atkinson_10']:.4f}   "
+            f"| {r['min_fulfillment']:.4f}    "
+            f"| {r['sampang']:.4f} "
+            f"| {r['bangkalan']:.4f}    |"
+        )
+        lines.append(line)
+    return lines
+
+
+def _format_sensitivity(sens_rows, caption=""):
+    """Format sensitivity rows as Markdown table lines."""
+    lines = []
+    if caption:
+        lines.append(f"### {caption}")
+        lines.append("")
+    header = (
+        "| Variant | Coverage | Gini  | MinFull | Sampang | Bangkalan | Description |"
+    )
+    sep = (
+        "|---------|----------|-------|---------|---------|-----------|-------------|"
+    )
+    lines.append(header)
+    lines.append(sep)
+    for r in sens_rows:
+        line = (
+            f"| {r['variant']:<7s} "
+            f"| {r['total_deficit_covered']:.4f}   "
+            f"| {r['gini']:.4f}"
+            f"| {r['min_fulfillment']:.4f} "
+            f"| {r['sampang']:.4f} "
+            f"| {r['bangkalan']:.4f}    "
+            f"| {r['desc']} |"
+        )
+        lines.append(line)
+    return lines
+
+
+def main():
+    print("=" * 80)
+    print("  AGRIFLOW EQUITY COMPARISON — ABUNDANT vs CONSTRAINED")
+    print("=" * 80)
+
+    logistics = LogisticsContext()
+
+    # -----------------------------------------------------------------------
+    # ABUNDANT data (canonical)
+    # -----------------------------------------------------------------------
+    print("  [ABUNDANT] Loading canonical Jatim sample data ...")
+    data_a = load_all_sample_data()
+    surplus_a = data_a["surplus"]
+    deficit_a = data_a["deficit"]
+    weather = data_a["weather"]
+    historical = data_a["historical_prices"]
+    kabupaten_dict = data_a["kabupaten"]
+    demand_tons_a = _build_demand_tons(deficit_a)
+
+    total_surplus_a = sum(s.volume_tons for s in surplus_a)
+    total_deficit_a = sum(d.volume_tons for d in deficit_a)
+    print(f"  ABUNDANT  — surplus={total_surplus_a:.0f}t, deficit={total_deficit_a:.0f}t, "
+          f"ratio={total_surplus_a/total_deficit_a:.3f}")
+
+    # -----------------------------------------------------------------------
+    # CONSTRAINED data (La Nina shock)
+    # -----------------------------------------------------------------------
+    print("  [CONSTRAINED] Loading La Nina flood shock data ...")
+    print(f"    Shock: Ngawi(3521)+Madiun(3519)+Bojonegoro(3522) banjir bersamaan.")
+    print(f"    Removed: beras_premium 1150t + beras_medium 2100t + jagung 1400t")
+    print(f"    Fixture: sample_data/{CONSTRAINED_CSV}")
+    data_c = load_all_sample_data(surplus_deficit_csv=CONSTRAINED_CSV)
+    surplus_c = data_c["surplus"]
+    deficit_c = data_c["deficit"]
+    demand_tons_c = _build_demand_tons(deficit_c)
+
+    total_surplus_c = sum(s.volume_tons for s in surplus_c)
+    total_deficit_c = sum(d.volume_tons for d in deficit_c)
+    print(f"  CONSTRAINED — surplus={total_surplus_c:.0f}t, deficit={total_deficit_c:.0f}t, "
+          f"ratio={total_surplus_c/total_deficit_c:.3f}  [UNDER-SUPPLIED]")
+    print()
+
+    # -----------------------------------------------------------------------
+    # Run five strategies on BOTH scenarios
+    # -----------------------------------------------------------------------
+    print("  Running 5 strategies x 2 scenarios (10 matching runs) ...")
+    strategies_a = _run_five_strategies(surplus_a, deficit_a, logistics, weather, historical)
+    print("    ABUNDANT done.")
+    strategies_c = _run_five_strategies(surplus_c, deficit_c, logistics, weather, historical)
+    print("    CONSTRAINED done.")
+    print()
+
+    strategy_order = ["pure_greedy", "agriflow", "uniform", "proportional", "agriflow_smoothed"]
+
+    rows_a = [compute_row(s, strategies_a[s], demand_tons_a) for s in strategy_order]
+    rows_c = [compute_row(s, strategies_c[s], demand_tons_c) for s in strategy_order]
+
+    # -----------------------------------------------------------------------
+    # Run sensitivity on BOTH scenarios
+    # -----------------------------------------------------------------------
+    print("  Running Action 6 sensitivity x 2 scenarios (6 matching runs) ...")
+    sens_a = _run_sensitivity(surplus_a, deficit_a, logistics, weather, historical, demand_tons_a)
+    print("    ABUNDANT sensitivity done.")
+    sens_c = _run_sensitivity(surplus_c, deficit_c, logistics, weather, historical, demand_tons_c)
+    print("    CONSTRAINED sensitivity done.")
+    print()
+
+    # -----------------------------------------------------------------------
+    # Print TABLE 1A — ABUNDANT
+    # -----------------------------------------------------------------------
+    lines_1a = _format_table1(rows_a, demand_tons_a, caption="ABUNDANT (surplus=8612t, deficit=5249t, ratio=1.641)")
+    lines_1c = _format_table1(rows_c, demand_tons_c, caption="CONSTRAINED / La Nina banjir Ngawi+Madiun+Bojonegoro (surplus=3962t, deficit=5249t, ratio=0.754)")
+
+    print("=" * 80)
+    print("  TABLE 1A — BASELINE COMPARISON (ABUNDANT scenario)")
+    print("=" * 80)
+    for line in lines_1a:
+        print("  " + line)
+    print()
+
+    print("=" * 80)
+    print("  TABLE 1C — BASELINE COMPARISON (CONSTRAINED scenario)")
+    print("=" * 80)
+    for line in lines_1c:
+        print("  " + line)
+    print()
+
+    # -----------------------------------------------------------------------
+    # Print TABLE 2 — Sensitivity
+    # -----------------------------------------------------------------------
+    lines_2a = _format_sensitivity(sens_a, caption="Sensitivity ABUNDANT")
+    lines_2c = _format_sensitivity(sens_c, caption="Sensitivity CONSTRAINED")
+
+    print("=" * 80)
+    print("  TABLE 2C — ACTION 6 SENSITIVITY (CONSTRAINED scenario)")
+    print("  Note: ABUNDANT sensitivity is degenerate (all 1.0000 for Sampang/Bangkalan).")
+    print("  CONSTRAINED sensitivity should show differentiation.")
+    print("=" * 80)
+    for line in lines_2c:
+        print("  " + line)
+    print()
+
+    # -----------------------------------------------------------------------
+    # Boundary perturbation (same kab population, scenario-independent)
+    # -----------------------------------------------------------------------
+    perturb = boundary_perturbation(kabupaten_dict)
+    print("=" * 80)
+    print("  BOUNDARY PERTURBATION (unchanged — same 38 Jatim kabs)")
+    print("=" * 80)
+    print("  | Threshold shift | Kabs changing tier |")
+    print("  |-----------------|---------------------|")
+    for delta in (-2.0, -1.0, +1.0, +2.0):
+        label = f"{delta:+.0f} pts"
+        print(f"  | {label:<15s} | {perturb[delta]:2d}                  |")
+    print()
+
+    # -----------------------------------------------------------------------
+    # ORDERING CHECKS — CONSTRAINED (where the equity story plays out)
+    # -----------------------------------------------------------------------
+    print("  ORDERING CHECKS — CONSTRAINED scenario:")
+    check = lambda ok, msg: print(f"  {'PASS' if ok else 'FAIL (!) '} {msg}")
+
+    g_cov = rows_c[0]["total_deficit_covered"]
+    a_cov = rows_c[1]["total_deficit_covered"]
+    g_gini = rows_c[0]["gini"]
+    a_gini = rows_c[1]["gini"]
+    u_gini = rows_c[2]["gini"]
+    a_min = rows_c[1]["min_fulfillment"]
+    g_min = rows_c[0]["min_fulfillment"]
+    a_samp = rows_c[1]["sampang"]
+    g_samp = rows_c[0]["sampang"]
+    a_bang = rows_c[1]["bangkalan"]
+    g_bang = rows_c[0]["bangkalan"]
+    u_samp = rows_c[2]["sampang"]
+
+    # Gini sanity check: uniform ~0 even in constrained
+    check(u_gini < 0.05,
+          f"uniform Gini ({u_gini:.4f}) < 0.05 [sanity: formula correct in constrained]")
+    check(g_cov >= a_cov - 1e-9,
+          f"greedy coverage ({g_cov:.4f}) >= agriflow ({a_cov:.4f}) [efficiency frontier]")
+    check(a_gini <= g_gini + 1e-6,
+          f"agriflow Gini ({a_gini:.4f}) <= greedy Gini ({g_gini:.4f}) [equity boost visible]")
+    check(a_samp >= g_samp - 1e-9,
+          f"Sampang: agriflow ({a_samp:.4f}) >= greedy ({g_samp:.4f}) [1.30x boost works]")
+    check(a_bang >= g_bang - 1e-9,
+          f"Bangkalan: agriflow ({a_bang:.4f}) >= greedy ({g_bang:.4f}) [1.30x boost works]")
+    check(a_min >= g_min - 1e-9,
+          f"agriflow min_fulfillment ({a_min:.4f}) >= greedy ({g_min:.4f}) [leximin better]")
+
+    # Sensitivity: strict > lenient for Sampang under constrained
+    s_strict_samp = sens_c[0]["sampang"]
+    s_lenient_samp = sens_c[2]["sampang"]
+    sens_degenerate = abs(s_strict_samp - s_lenient_samp) < 1e-6
+    check(s_strict_samp >= s_lenient_samp - 1e-9,
+          f"strict Sampang ({s_strict_samp:.4f}) >= lenient ({s_lenient_samp:.4f})")
+    if sens_degenerate:
+        print("  !! SENSITIVITY STILL DEGENERATE for Sampang — equity mechanism may need review")
+    else:
+        print(f"  ** Sensitivity spread: strict-lenient Sampang delta = "
+              f"{s_strict_samp - s_lenient_samp:+.4f} [non-degenerate]")
+
+    # Summary interpretation
+    print()
+    print("  INTERPRETATION:")
+    if a_samp > g_samp + 1e-4:
+        print(f"  + AgriFlow protects Sampang (+{(a_samp-g_samp)*100:.1f}pp vs greedy)")
+    else:
+        print(f"  ~ Sampang: AgriFlow = greedy (delta={a_samp-g_samp:+.4f})")
+    if a_bang > g_bang + 1e-4:
+        print(f"  + AgriFlow protects Bangkalan (+{(a_bang-g_bang)*100:.1f}pp vs greedy)")
+    else:
+        print(f"  ~ Bangkalan: AgriFlow = greedy (delta={a_bang-g_bang:+.4f})")
+    if a_gini < g_gini - 1e-4:
+        print(f"  + AgriFlow Gini lower than greedy ({a_gini:.4f} vs {g_gini:.4f}): equity visible")
+    else:
+        print(f"  ~ Gini: AgriFlow ({a_gini:.4f}) vs greedy ({g_gini:.4f}) — marginal or no improvement")
+    cost_pp = (g_cov - a_cov) * 100
+    if cost_pp > 0.05:
+        print(f"  - Coverage cost: AgriFlow sacrifices {cost_pp:.1f}pp aggregate coverage for equity")
+    else:
+        print(f"  ~ Coverage cost: negligible ({cost_pp:.2f}pp)")
+    print()
+
+    # -----------------------------------------------------------------------
+    # WRITE OUTPUT
+    # -----------------------------------------------------------------------
+    output_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "output")
+    os.makedirs(output_dir, exist_ok=True)
+    output_path = os.path.join(output_dir, "equity_comparison_constrained.md")
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write("# AgriFlow Equity Comparison — ABUNDANT vs CONSTRAINED\n\n")
+        f.write("Generated by `benchmarks/equity_comparison_constrained.py`.\n\n")
+        f.write("## Scenario: La Nina Supply Shock (CONSTRAINED)\n\n")
+        f.write("**Narasi:** La Nina banjir besar menghantam tiga sentra beras utama Jatim\n")
+        f.write("bagian barat — Ngawi (3521), Madiun (3519), Bojonegoro (3522) — secara\n")
+        f.write("bersamaan. Ketiga kab berada di dataran rendah lembah Bengawan Solo dan\n")
+        f.write("anak sungainya; pola banjir simultan terdokumentasi pada La Nina 2010,\n")
+        f.write("2020–21, dan 2022–23.\n\n")
+        f.write("**Dampak:** 6 surplus rows dihapus:\n\n")
+        f.write("| Kab | Nama | Komoditas | Volume (t) |\n")
+        f.write("|-----|------|-----------|------------|\n")
+        f.write("| 3521 | Ngawi | beras_premium | 500 |\n")
+        f.write("| 3521 | Ngawi | beras_medium | 900 |\n")
+        f.write("| 3521 | Ngawi | jagung | 600 |\n")
+        f.write("| 3519 | Madiun | beras_medium | 1200 |\n")
+        f.write("| 3522 | Bojonegoro | beras_premium | 650 |\n")
+        f.write("| 3522 | Bojonegoro | jagung | 800 |\n")
+        f.write("| **Total** | | | **4650** |\n\n")
+        f.write("**Arithmetic:**\n\n")
+        f.write("| Scenario | Surplus (t) | Deficit (t) | Ratio |\n")
+        f.write("|----------|-------------|-------------|-------|\n")
+        f.write(f"| ABUNDANT    | 8612 | 5249 | 1.641 (over-supplied) |\n")
+        f.write(f"| CONSTRAINED | 3962 | 5249 | 0.754 (under-supplied by 32.5%) |\n\n")
+        f.write("Fixture: `sample_data/surplus_deficit_constrained.csv` (committed).\n\n")
+        f.write("---\n\n")
+        f.write("## Table 1A — Baseline Comparison: ABUNDANT\n\n")
+        f.write("Coverage = volume-weighted tons fulfilled / tons demanded.  \n")
+        f.write("Gini / Atkinson = weighted by demand volume; lower = more equitable.  \n")
+        f.write("MinFulfill = fulfillment ratio of worst-served demand node.  \n")
+        f.write("Sampang=3527 (IPM 66.72), Bangkalan=3526 (IPM 67.70).  \n\n")
+        for line in lines_1a:
+            f.write(line + "\n")
+        f.write("\n")
+        f.write("## Table 1C — Baseline Comparison: CONSTRAINED\n\n")
+        f.write("Same metrics. Under supply shortage, equity tradeoffs become observable.\n\n")
+        for line in lines_1c:
+            f.write(line + "\n")
+        f.write("\n")
+        f.write("## Table 2A — Sensitivity: ABUNDANT (degenerate — included for completeness)\n\n")
+        for line in lines_2a:
+            f.write(line + "\n")
+        f.write("\n")
+        f.write("## Table 2C — Sensitivity: CONSTRAINED\n\n")
+        f.write("`current` delegates to `equity_multiplier_value` — single source of truth.\n\n")
+        for line in lines_2c:
+            f.write(line + "\n")
+        f.write("\n")
+        f.write("## Boundary Perturbation\n\n")
+        f.write("Same 38 Jatim kabs in both scenarios. Scenario-independent.\n\n")
+        f.write("| Threshold shift | Kabs changing tier |\n")
+        f.write("|-----------------|---------------------|\n")
+        for delta in (-2.0, -1.0, +1.0, +2.0):
+            label = f"{delta:+.0f} pts"
+            f.write(f"| {label:<15s} | {perturb[delta]:2d}                  |\n")
+        f.write("\n")
+
+    print(f"  Tables written to: {output_path}")
+    print("=" * 80)
+    print("  DONE.")
+    print("=" * 80)
+
+
+if __name__ == "__main__":
+    main()

benchmarks/greedy_vs_optimal.py

@@ -0,0 +1,518 @@
+"""
+benchmarks/greedy_vs_optimal.py — Greedy vs exact optimal, on AgriFlow's own
+score/cost structure.
+
+WHY THIS SCRIPT EXISTS
+-----------------------
+HANDOFF.md (2026-05-19) HOLDs the POT/EMD (optimal transport) allocator on the
+claim: "AgriFlow pakai single shared score function -> solusi POT/EMD pada cost
+matrix saat ini identik atau hampir-identik dengan greedy." That claim rests on
+ONE 3x3 toy example where greedy happened to match brute-force optimal (2.720).
+
+A single-instance coincidence is not evidence. This script settles the question
+empirically and reproducibly, in two parts:
+
+  PART A — Assignment case (1-to-1 matching, no volume splitting):
+      A1. Pure uniform-random scores (baseline literature check).
+      A2. AgriFlow-structured scores: built from the project's own
+          ScoreBreakdown.weighted_total() (22/22/22/18/16 weights,
+          matching_engine/models.py), with correlated supply/demand
+          "quality" so the instances are not adversarial.
+      Compared: naive greedy (repeatedly take the best remaining pair) vs
+      scipy.optimize.linear_sum_assignment (Hungarian algorithm, EXACT optimal).
+      For n<=6 the Hungarian result is cross-checked against brute-force
+      permutation search as a correctness sanity check on the solver itself.
+
+  PART B — Capacitated / divisible case (the actual production shape):
+      Runs the REAL engine pipeline — matching_engine.constraints.generate_candidates
+      (Layer 1 hard constraints) + matching_engine.scoring.compute_score (Layer 2,
+      DEFAULT_WEIGHTS) + matching_engine.allocation equity/segment multipliers —
+      on (a) the project's real Jatim sample data (sample_data/surplus_deficit.csv)
+      and (b) synthetic Indonesia-scale workloads (reusing benchmarks/national_scale
+      generators) at increasing kab counts.
+      Compared: the SHIPPED allocators (stable_match_tier1 via force_strategy=
+      "stable", greedy_match_tier2 via force_strategy="greedy") vs the exact
+      capacitated transportation optimum, solved as an LP with scipy.optimize.linprog
+      (HiGHS): maximize sum(final_score_e * x_e) subject to per-supply-node and
+      per-deficit-node capacity constraints, 0 <= x_e <= min(supply, demand).
+      This LP is the textbook optimal solution to the "correct" framing raised
+      separately (capacitated min-cost transportation, not 1-1 assignment) — it
+      is what network-simplex / ot.emd-with-partial-mass would also converge to.
+
+      Also reports STRANDED VOLUME for the 1-1 stable matcher: how much supply/
+      demand tonnage is left on the table because stable_match_tier1 matches at
+      most one deficit per surplus node (min(s,d) then abandon), vs the LP/greedy
+      which can split a big surplus across many small deficits.
+
+Everything is seeded (--seed, default 2026) for reproducibility. No network
+calls, no writes outside benchmarks/output/.
+
+Usage:
+    python benchmarks/greedy_vs_optimal.py
+    python benchmarks/greedy_vs_optimal.py --skip-real     # synthetic sweeps only (fast)
+    python benchmarks/greedy_vs_optimal.py --seed 7
+"""
+
+from __future__ import annotations
+
+import argparse
+import itertools
+import json
+import os
+import random
+import statistics
+import sys
+import time
+from dataclasses import dataclass, asdict
+from datetime import datetime
+from typing import Callable, List, Optional, Sequence, Tuple
+
+import numpy as np
+from scipy.optimize import linear_sum_assignment, linprog
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except (AttributeError, OSError):
+        pass
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)
+
+from matching_engine.allocation import (
+    allocate, equity_multiplier_value, segment_multiplier_value,
+)
+from matching_engine.constraints import generate_candidates
+from matching_engine.models import LogisticsContext, ScoreBreakdown
+from matching_engine.scoring import DEFAULT_WEIGHTS, compute_score
+from sample_data.loader import load_all_sample_data
+
+DEFAULT_SEED = 2026
+
+
+# =============================================================================
+# PART A — ASSIGNMENT CASE (1-to-1, no volume splitting)
+# =============================================================================
+
+def brute_force_optimal(score: np.ndarray) -> float:
+    """Exact optimal via exhaustive permutation search. Only for n <= 8."""
+    n, m = score.shape
+    assert n == m, "brute force sanity check only used on square matrices here"
+    best = -1.0
+    for perm in itertools.permutations(range(n)):
+        total = sum(score[i, perm[i]] for i in range(n))
+        if total > best:
+            best = total
+    return best
+
+
+def hungarian_optimal(score: np.ndarray) -> Tuple[float, List[Tuple[int, int]]]:
+    """Exact optimal assignment (max total score) via scipy Hungarian algorithm."""
+    row_ind, col_ind = linear_sum_assignment(-score)  # minimize negative = maximize
+    total = float(score[row_ind, col_ind].sum())
+    pairs = list(zip(row_ind.tolist(), col_ind.tolist()))
+    return total, pairs
+
+
+def greedy_assignment(score: np.ndarray) -> Tuple[float, List[Tuple[int, int]]]:
+    """
+    Naive greedy 1-1 assignment: repeatedly take the globally best remaining
+    (row, col) pair. This is the abstraction of what stable_match_tier1 /
+    greedy_match_tier2 do at the single-score level (both eventually assign the
+    best-scoring available counterpart first).
+    """
+    n, m = score.shape
+    flat = [(score[i, j], i, j) for i in range(n) for j in range(m)]
+    flat.sort(key=lambda t: -t[0])
+    used_rows, used_cols = set(), set()
+    pairs = []
+    total = 0.0
+    for s, i, j in flat:
+        if i in used_rows or j in used_cols:
+            continue
+        used_rows.add(i)
+        used_cols.add(j)
+        pairs.append((i, j))
+        total += s
+        if len(used_rows) == min(n, m):
+            break
+    return total, pairs
+
+
+@dataclass
+class AssignmentTrialResult:
+    n: int
+    trial: int
+    greedy_total: float
+    optimal_total: float
+    gap_pct: float           # (optimal - greedy) / optimal * 100
+    greedy_lost: bool        # strictly worse than optimal
+
+
+def run_assignment_sweep(
+    label: str,
+    ns: Sequence[int],
+    trials: int,
+    make_score_matrix: Callable[[int, random.Random], np.ndarray],
+    seed: int,
+    sanity_check_bruteforce: bool = True,
+) -> List[AssignmentTrialResult]:
+    results: List[AssignmentTrialResult] = []
+    rng = random.Random(seed)
+
+    print(f"\n{'=' * 78}")
+    print(f"  PART A — {label}")
+    print(f"{'=' * 78}")
+
+    for n in ns:
+        losses = 0
+        gaps = []
+        for t in range(trials):
+            score = make_score_matrix(n, rng)
+            greedy_total, _ = greedy_assignment(score)
+            optimal_total, _ = hungarian_optimal(score)
+
+            if sanity_check_bruteforce and n <= 6 and t == 0:
+                bf = brute_force_optimal(score)
+                assert abs(bf - optimal_total) < 1e-6, (
+                    f"Hungarian ({optimal_total}) != brute force ({bf}) at n={n} — "
+                    f"solver correctness check failed"
+                )
+
+            gap_pct = (
+                0.0 if optimal_total <= 1e-12
+                else (optimal_total - greedy_total) / optimal_total * 100.0
+            )
+            lost = greedy_total < optimal_total - 1e-9
+            if lost:
+                losses += 1
+            gaps.append(gap_pct)
+            results.append(AssignmentTrialResult(
+                n=n, trial=t, greedy_total=greedy_total,
+                optimal_total=optimal_total, gap_pct=gap_pct, greedy_lost=lost,
+            ))
+
+        mean_gap = statistics.mean(gaps)
+        median_gap = statistics.median(gaps)
+        worst_gap = max(gaps)
+        print(f"  n={n:>3}  trials={trials:>4}  greedy lost {losses:>4}/{trials} "
+              f"({losses / trials * 100:5.1f}%)  mean_gap={mean_gap:6.2f}%  "
+              f"median_gap={median_gap:6.2f}%  worst_gap={worst_gap:6.2f}%")
+
+    return results
+
+
+def make_uniform_score_matrix(n: int, rng: random.Random) -> np.ndarray:
+    """Pure iid uniform random scores in [0, 1] — n x n."""
+    return np.array([[rng.random() for _ in range(n)] for _ in range(n)])
+
+
+def make_agriflow_structured_score_matrix(n: int, rng: random.Random) -> np.ndarray:
+    """
+    n x n score matrix built from the project's OWN ScoreBreakdown.weighted_total()
+    (22/22/22/18/16 weights, matching_engine/models.py) instead of an abstract
+    number. Supply node i has a fixed "quality" vector; deficit node j has a fixed
+    "preference" vector; per-pair dimension score = clip(quality_i + pref_j + noise,
+    0, 1). This gives correlated, non-adversarial instances structurally similar to
+    a real (supply, deficit) grid, while still being driven by the actual weighted-
+    sum formula the engine uses everywhere.
+    """
+    dims = 5  # distance, volume, price, perishability, climate
+    supply_quality = [[rng.random() for _ in range(dims)] for _ in range(n)]
+    demand_pref = [[rng.random() for _ in range(dims)] for _ in range(n)]
+
+    score = np.zeros((n, n))
+    for i in range(n):
+        for j in range(n):
+            vals = []
+            for d in range(dims):
+                noise = rng.gauss(0, 0.10)
+                v = 0.5 * supply_quality[i][d] + 0.5 * demand_pref[j][d] + noise
+                vals.append(min(1.0, max(0.0, v)))
+            breakdown = ScoreBreakdown(
+                distance=vals[0], volume=vals[1], price=vals[2],
+                perishability=vals[3], climate=vals[4],
+            )
+            score[i, j] = breakdown.weighted_total()  # 0-100 scale, project's own formula
+    return score
+
+
+# =============================================================================
+# PART B — CAPACITATED / DIVISIBLE CASE (real engine pipeline)
+# =============================================================================
+
+@dataclass
+class CapacitatedResult:
+    label: str
+    n_supply: int
+    n_deficit: int
+    n_candidates: int
+    total_supply_tons: float
+    total_deficit_tons: float
+    stable_welfare: float
+    stable_matched_tons: float
+    stable_n_matches: int
+    greedy_welfare: float
+    greedy_matched_tons: float
+    greedy_n_matches: int
+    lp_optimal_welfare: float
+    lp_optimal_matched_tons: float
+    lp_status: str
+    stable_gap_pct: float     # vs LP optimal welfare
+    greedy_gap_pct: float     # vs LP optimal welfare
+    stable_stranded_tons: float   # total_supply_tons - stable_matched_tons
+    lp_stranded_tons: float       # total_supply_tons - lp_optimal_matched_tons
+
+
+def _final_score(s, d, base_score: float) -> float:
+    eq_mult = equity_multiplier_value(d.kabupaten.ipm)
+    seg_mult, _flags = segment_multiplier_value(s, d)
+    return base_score * eq_mult * seg_mult
+
+
+def solve_capacitated_transportation_lp(
+    candidates: List[Tuple], score_fn: Callable,
+) -> Tuple[float, float, str, dict]:
+    """
+    Exact optimal for the capacitated (divisible) transportation problem on the
+    SAME candidate pool the engine itself uses (post Layer-1 filtering).
+
+    max  sum_e final_score_e * x_e
+    s.t. for each supply node i: sum_{e incident to i} x_e <= supply_volume_i
+         for each deficit node j: sum_{e incident to j} x_e <= deficit_volume_j
+         0 <= x_e <= min(supply_i, deficit_j)   (per-edge bound, redundant but tightens LP)
+
+    Solved with scipy.optimize.linprog (HiGHS). Returns (optimal_welfare,
+    optimal_matched_tons, lp_status, edge_solution) where edge_solution maps
+    edge index -> tons matched.
+    """
+    if not candidates:
+        return 0.0, 0.0, "no_candidates", {}
+
+    supply_keys, deficit_keys = {}, {}
+    edges = []  # (supply_idx, deficit_idx, final_score, cap, s, d)
+    score_cache = {}
+
+    for s, d in candidates:
+        s_key = s.kabupaten.id + "_" + s.commodity.code
+        d_key = d.kabupaten.id + "_" + d.commodity.code + "_" + d.segment.value
+        if s_key not in supply_keys:
+            supply_keys[s_key] = (len(supply_keys), s.volume_tons)
+        if d_key not in deficit_keys:
+            deficit_keys[d_key] = (len(deficit_keys), d.volume_tons)
+
+        cache_key = (s_key, d.kabupaten.id + "_" + d.commodity.code)
+        if cache_key not in score_cache:
+            _breakdown, base_score, _dist = score_fn(s, d)
+            score_cache[cache_key] = _final_score(s, d, base_score)
+        fscore = score_cache[cache_key]
+
+        s_idx = supply_keys[s_key][0]
+        d_idx = deficit_keys[d_key][0]
+        cap = min(s.volume_tons, d.volume_tons)
+        edges.append((s_idx, d_idx, fscore, cap))
+
+    n_edges = len(edges)
+    n_supply = len(supply_keys)
+    n_deficit = len(deficit_keys)
+
+    c = np.array([-e[2] for e in edges])  # minimize negative = maximize welfare
+    bounds = [(0.0, e[3]) for e in edges]
+
+    A_ub = np.zeros((n_supply + n_deficit, n_edges))
+    b_ub = np.zeros(n_supply + n_deficit)
+    for s_key, (idx, vol) in supply_keys.items():
+        b_ub[idx] = vol
+    for d_key, (idx, vol) in deficit_keys.items():
+        b_ub[n_supply + idx] = vol
+    for e_idx, (s_idx, d_idx, _fscore, _cap) in enumerate(edges):
+        A_ub[s_idx, e_idx] = 1.0
+        A_ub[n_supply + d_idx, e_idx] = 1.0
+
+    res = linprog(c, A_ub=A_ub, b_ub=b_ub, bounds=bounds, method="highs")
+
+    if not res.success:
+        return 0.0, 0.0, f"lp_failed:{res.message}", {}
+
+    optimal_welfare = float(-res.fun)
+    matched_tons = float(res.x.sum())
+    edge_solution = {i: float(x) for i, x in enumerate(res.x) if x > 1e-9}
+    return optimal_welfare, matched_tons, "optimal", edge_solution
+
+
+def evaluate_capacitated(
+    label: str, surplus, deficit, logistics: Optional[LogisticsContext] = None,
+) -> CapacitatedResult:
+    logistics = logistics or LogisticsContext()
+    candidates = generate_candidates(surplus, deficit, logistics=logistics)
+
+    def score_fn(s, d):
+        return compute_score(s, d, logistics=logistics, weights=DEFAULT_WEIGHTS)
+
+    total_supply_tons = sum(s.volume_tons for s in surplus)
+    total_deficit_tons = sum(d.volume_tons for d in deficit)
+
+    if not candidates:
+        return CapacitatedResult(
+            label=label, n_supply=len(surplus), n_deficit=len(deficit),
+            n_candidates=0, total_supply_tons=total_supply_tons,
+            total_deficit_tons=total_deficit_tons,
+            stable_welfare=0.0, stable_matched_tons=0.0, stable_n_matches=0,
+            greedy_welfare=0.0, greedy_matched_tons=0.0, greedy_n_matches=0,
+            lp_optimal_welfare=0.0, lp_optimal_matched_tons=0.0, lp_status="no_candidates",
+            stable_gap_pct=0.0, greedy_gap_pct=0.0,
+            stable_stranded_tons=total_supply_tons, lp_stranded_tons=total_supply_tons,
+        )
+
+    matches_stable = allocate(candidates, score_fn, force_strategy="stable",
+                               equity_fn=equity_multiplier_value)
+    matches_greedy = allocate(candidates, score_fn, force_strategy="greedy",
+                               equity_fn=equity_multiplier_value)
+
+    stable_welfare = sum(m.final_score * m.matched_volume_tons for m in matches_stable)
+    stable_matched_tons = sum(m.matched_volume_tons for m in matches_stable)
+    greedy_welfare = sum(m.final_score * m.matched_volume_tons for m in matches_greedy)
+    greedy_matched_tons = sum(m.matched_volume_tons for m in matches_greedy)
+
+    lp_welfare, lp_matched_tons, lp_status, _sol = solve_capacitated_transportation_lp(
+        candidates, score_fn,
+    )
+
+    def gap(engine_welfare: float) -> float:
+        if lp_welfare <= 1e-9:
+            return 0.0
+        return (lp_welfare - engine_welfare) / lp_welfare * 100.0
+
+    return CapacitatedResult(
+        label=label, n_supply=len(surplus), n_deficit=len(deficit),
+        n_candidates=len(candidates),
+        total_supply_tons=total_supply_tons, total_deficit_tons=total_deficit_tons,
+        stable_welfare=stable_welfare, stable_matched_tons=stable_matched_tons,
+        stable_n_matches=len(matches_stable),
+        greedy_welfare=greedy_welfare, greedy_matched_tons=greedy_matched_tons,
+        greedy_n_matches=len(matches_greedy),
+        lp_optimal_welfare=lp_welfare, lp_optimal_matched_tons=lp_matched_tons,
+        lp_status=lp_status,
+        stable_gap_pct=gap(stable_welfare), greedy_gap_pct=gap(greedy_welfare),
+        stable_stranded_tons=total_supply_tons - stable_matched_tons,
+        lp_stranded_tons=total_supply_tons - lp_matched_tons,
+    )
+
+
+def print_capacitated_result(r: CapacitatedResult) -> None:
+    print(f"\n  --- {r.label} ---")
+    print(f"  supply={r.n_supply}  deficit={r.n_deficit}  candidates={r.n_candidates}  "
+          f"total_supply={r.total_supply_tons:,.0f}t  total_deficit={r.total_deficit_tons:,.0f}t")
+    print(f"  {'strategy':<22}{'welfare':>14}{'matched_tons':>16}{'n_matches':>12}{'gap_vs_LP':>12}")
+    print(f"  {'stable (shipped)':<22}{r.stable_welfare:>14,.1f}{r.stable_matched_tons:>16,.1f}"
+          f"{r.stable_n_matches:>12}{r.stable_gap_pct:>11.2f}%")
+    print(f"  {'greedy (shipped)':<22}{r.greedy_welfare:>14,.1f}{r.greedy_matched_tons:>16,.1f}"
+          f"{r.greedy_n_matches:>12}{r.greedy_gap_pct:>11.2f}%")
+    print(f"  {'LP optimal (exact)':<22}{r.lp_optimal_welfare:>14,.1f}{r.lp_optimal_matched_tons:>16,.1f}"
+          f"{'-':>12}{'0.00%':>12}   [{r.lp_status}]")
+    print(f"  stranded supply tons: stable={r.stable_stranded_tons:,.1f}t  "
+          f"LP-optimal={r.lp_stranded_tons:,.1f}t  "
+          f"(extra tonnage LP moves that stable abandons: "
+          f"{r.stable_stranded_tons - r.lp_stranded_tons:,.1f}t)")
+
+
+# =============================================================================
+# MAIN
+# =============================================================================
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Greedy vs exact-optimal benchmark for AgriFlow's allocator "
+                     "(settles HANDOFF.md's POT/EMD HOLD premise with evidence).",
+    )
+    parser.add_argument("--seed", type=int, default=DEFAULT_SEED)
+    parser.add_argument("--trials", type=int, default=200,
+                         help="Trials per n in the assignment sweeps (default 200)")
+    parser.add_argument("--skip-real", action="store_true",
+                         help="Skip Part B real-data / synthetic-Indonesia runs (faster)")
+    parser.add_argument("--json-out", type=str, default=None,
+                         help="Optional path to write full results as JSON")
+    args = parser.parse_args()
+
+    t0 = time.perf_counter()
+    print("=" * 78)
+    print(f"  AgriFlow — Greedy vs Exact Optimal  (seed={args.seed}, "
+          f"trials/n={args.trials})")
+    print(f"  Run: {datetime.now().isoformat(timespec='seconds')}")
+    print("=" * 78)
+
+    all_results: dict = {"seed": args.seed, "trials": args.trials}
+
+    ns = [3, 4, 5, 6, 7, 10, 12, 15, 20]
+
+    a1 = run_assignment_sweep(
+        "A1 — Pure uniform-random scores (assignment case)",
+        ns, args.trials, make_uniform_score_matrix, args.seed,
+    )
+    a2 = run_assignment_sweep(
+        "A2 — AgriFlow-structured scores (ScoreBreakdown.weighted_total, "
+        "correlated supply/demand)",
+        ns, args.trials, make_agriflow_structured_score_matrix, args.seed + 1,
+    )
+    all_results["part_a_uniform"] = [asdict(r) for r in a1]
+    all_results["part_a_agriflow_structured"] = [asdict(r) for r in a2]
+
+    if not args.skip_real:
+        print(f"\n{'=' * 78}")
+        print("  PART B — Capacitated transportation (real engine pipeline)")
+        print(f"{'=' * 78}")
+
+        cap_results: List[CapacitatedResult] = []
+
+        # B1 — Real Jatim sample data (the project's actual demo dataset)
+        data = load_all_sample_data()
+        r_real = evaluate_capacitated(
+            "B1 — Real Jatim sample data (sample_data/surplus_deficit.csv, 38 kab)",
+            data["surplus"], data["deficit"],
+        )
+        print_capacitated_result(r_real)
+        cap_results.append(r_real)
+
+        # B2 — Synthetic Indonesia-scale workloads at increasing kab counts,
+        # reusing the project's own national_scale.py generators (real Commodity
+        # specs, realistic IPM/tier distribution).
+        sys.path.insert(0, os.path.join(ROOT, "benchmarks"))
+        import national_scale as ns_bench  # project's own synthetic generator
+
+        rng_synth = random.Random(args.seed)
+        random.seed(args.seed)  # national_scale generators use the global random module
+        for n_kab in (38, 100, 250):
+            kabs = ns_bench.make_synthetic_indonesia(n_kab)
+            surplus, deficit = ns_bench.make_workload(kabs, n_commodities=19)
+            r = evaluate_capacitated(
+                f"B2 — Synthetic Indonesia-scale ({n_kab} kab x 19 komoditas)",
+                surplus, deficit,
+            )
+            print_capacitated_result(r)
+            cap_results.append(r)
+
+        all_results["part_b_capacitated"] = [asdict(r) for r in cap_results]
+
+    elapsed = time.perf_counter() - t0
+    print(f"\n{'=' * 78}")
+    print(f"  Done in {elapsed:.1f}s")
+    print("=" * 78)
+
+    if args.json_out:
+        def _json_default(o):
+            if isinstance(o, (np.floating, np.integer)):
+                return o.item()
+            if isinstance(o, np.bool_):
+                return bool(o)
+            raise TypeError(f"Object of type {o.__class__.__name__} is not JSON serializable")
+
+        os.makedirs(os.path.dirname(args.json_out) or ".", exist_ok=True)
+        with open(args.json_out, "w", encoding="utf-8") as fh:
+            json.dump(all_results, fh, indent=2, default=_json_default)
+        print(f"  Full results written to {args.json_out}")
+
+
+if __name__ == "__main__":
+    main()

benchmarks/latency.py

@@ -0,0 +1,189 @@
+"""
+AgriFlow Matching Engine — Latency Benchmark
+=============================================
+
+Measure end-to-end latency dengan multiple konfigurasi untuk memvalidasi
+klaim "<500ms p99 untuk 38 kab × 19 komoditas" (Section 5.5.4).
+
+Run:
+    python benchmarks/latency.py
+
+Output:
+    Tabel p50/p95/p99/max latency untuk:
+        - Sample data current (40 supply × 33 deficit)
+        - Stress: synthetic 38 kab × 19 komoditas full
+        - Stress: 100 supply × 100 deficit (large)
+"""
+from __future__ import annotations
+import os
+import statistics
+import sys
+import time
+from datetime import datetime
+
+# Force UTF-8 stdio di Windows.
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except (AttributeError, OSError):
+        pass
+
+# Add project root ke path
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from matching_engine import (
+    Commodity, DemandNode, Kabupaten, LogisticsContext, SupplyNode, Tier,
+    run_matching,
+)
+from sample_data import load_all_sample_data
+from sample_data.generate_sample_data import KABUPATEN_DATA, KOMODITAS_DATA
+
+
+def percentile(data, p):
+    s = sorted(data)
+    k = (len(s) - 1) * p
+    f = int(k)
+    c = min(f + 1, len(s) - 1)
+    return s[f] + (s[c] - s[f]) * (k - f)
+
+
+def bench_one(label: str, supply, demand, weather=None, historical=None,
+              warmup: int = 5, iterations: int = 100) -> dict:
+    logistics = LogisticsContext()
+    # Warmup
+    for _ in range(warmup):
+        run_matching(supply, demand, logistics=logistics,
+                     weather_forecasts=weather, historical_prices=historical)
+    # Measure
+    samples = []
+    for _ in range(iterations):
+        t = time.perf_counter()
+        run_matching(supply, demand, logistics=logistics,
+                     weather_forecasts=weather, historical_prices=historical)
+        samples.append((time.perf_counter() - t) * 1000)
+    return {
+        "label": label,
+        "n_supply": len(supply),
+        "n_demand": len(demand),
+        "iterations": iterations,
+        "p50_ms": percentile(samples, 0.50),
+        "p95_ms": percentile(samples, 0.95),
+        "p99_ms": percentile(samples, 0.99),
+        "min_ms": min(samples),
+        "max_ms": max(samples),
+        "mean_ms": statistics.mean(samples),
+    }
+
+
+def make_synthetic_full_jatim():
+    """38 kab × 19 komoditas: setengah surplus, setengah deficit per komoditas."""
+    kabs = []
+    for kid, nama, lat, lon, ipm, pop, tier_s in KABUPATEN_DATA:
+        kabs.append(Kabupaten(
+            id=kid, nama=nama, latitude=lat, longitude=lon, ipm=ipm,
+            tier=Tier.HIGH if tier_s == "TIER_1_HIGH" else Tier.MEDIUM,
+            population=pop,
+        ))
+    komos = [
+        Commodity(code=c, nama=n, max_distance_km=md, min_viable_tons=mv,
+                  max_fresh_age_days=mf)
+        for c, n, md, mv, mf, _baseline in KOMODITAS_DATA
+    ]
+    surplus, deficit = [], []
+    for komo in komos:
+        for i, kab in enumerate(kabs):
+            if i % 2 == 0:
+                surplus.append(SupplyNode(
+                    kabupaten=kab, commodity=komo,
+                    volume_tons=max(komo.min_viable_tons * 5, 20.0),
+                    price_per_kg=30000, harvest_age_days=1,
+                ))
+            else:
+                deficit.append(DemandNode(
+                    kabupaten=kab, commodity=komo,
+                    volume_tons=max(komo.min_viable_tons * 4, 15.0),
+                    price_per_kg=50000,
+                ))
+    return surplus, deficit
+
+
+def make_synthetic_large(n_supply: int = 100, n_demand: int = 100):
+    """Stress test: scale beyond Jatim (project to national scale)."""
+    s, d = make_synthetic_full_jatim()
+    # Pad dengan duplikat (anggap nasional projection)
+    while len(s) < n_supply:
+        s.extend(s[:n_supply - len(s)])
+    while len(d) < n_demand:
+        d.extend(d[:n_demand - len(d)])
+    return s[:n_supply], d[:n_demand]
+
+
+def print_row(r):
+    print(f"  {r['label']:<35s} "
+          f"{r['n_supply']:>4d}×{r['n_demand']:<4d} "
+          f"p50={r['p50_ms']:>6.2f}  p95={r['p95_ms']:>6.2f}  "
+          f"p99={r['p99_ms']:>7.2f}  max={r['max_ms']:>7.2f}  "
+          f"mean={r['mean_ms']:>6.2f} ms")
+
+
+def main():
+    print("=" * 110)
+    print(f"  AgriFlow Matching Engine — Latency Benchmark "
+          f"({datetime.now().strftime('%Y-%m-%d %H:%M:%S')})")
+    print("=" * 110)
+    print(f"  Target Section 5.5.4: <500ms p99 untuk 38 kab × 19 komoditas")
+    print()
+
+    results = []
+
+    # 1. Sample data current
+    data = load_all_sample_data()
+    results.append(bench_one(
+        "Sample data CSV (realistic)",
+        data["surplus"], data["deficit"],
+        weather=data["weather"], historical=data["historical_prices"],
+    ))
+
+    # 2. Synthetic 38 kab × 19 komoditas full
+    s_full, d_full = make_synthetic_full_jatim()
+    results.append(bench_one(
+        "Synthetic full Jatim (38×19)",
+        s_full, d_full,
+    ))
+
+    # 3. Stress 100x100
+    s_100, d_100 = make_synthetic_large(100, 100)
+    results.append(bench_one(
+        "Stress 100×100 (national scale)",
+        s_100, d_100,
+        iterations=50,
+    ))
+
+    # 4. Stress 200x200
+    s_200, d_200 = make_synthetic_large(200, 200)
+    results.append(bench_one(
+        "Stress 200×200",
+        s_200, d_200,
+        iterations=30,
+    ))
+
+    print(f"  {'Configuration':<35s} {'N (s×d)':>9s}    {'p50':>9s}  "
+          f"{'p95':>9s}  {'p99':>11s}  {'max':>11s}  {'mean':>11s}")
+    print("  " + "-" * 106)
+    for r in results:
+        print_row(r)
+
+    print()
+    target = 500.0
+    p99_max = max(r["p99_ms"] for r in results)
+    if p99_max < target:
+        print(f"  PASS  semua konfigurasi p99 < {target}ms target "
+              f"(highest p99 = {p99_max:.2f}ms, "
+              f"margin {(target - p99_max) / target * 100:.1f}%)")
+    else:
+        print(f"  FAIL  p99 {p99_max:.2f}ms melebihi target {target}ms")
+    print()
+
+
+if __name__ == "__main__":
+    main()

benchmarks/national_scale.py

@@ -0,0 +1,185 @@
+"""
+National-scale stress test untuk AgriFlow Matching Engine.
+
+Indonesia: 514 kab/kota × 19 komoditas. Asumsi 50% surplus & 50% deficit
+per komoditas → ~4880 supply nodes, ~4880 demand nodes total.
+
+Ini test apakah engine v10 SIAP scale ke nasional, atau masih butuh
+optimization untuk handle volume itu.
+"""
+from __future__ import annotations
+import os
+import random
+import statistics
+import sys
+import time
+from datetime import datetime
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except (AttributeError, OSError):
+        pass
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from matching_engine import (
+    Commodity, DemandNode, Kabupaten, LogisticsContext, SupplyNode, Tier,
+    run_matching,
+)
+from sample_data.generate_sample_data import KOMODITAS_DATA
+
+
+def percentile(data, p):
+    s = sorted(data)
+    k = (len(s) - 1) * p
+    f = int(k)
+    c = min(f + 1, len(s) - 1)
+    return s[f] + (s[c] - s[f]) * (k - f)
+
+
+# Indonesia bounding box (kira-kira)
+# Sabang: -5.9, 95.3 | Merauke: -8.5, 140.4
+# Latitude: -11 to 6
+# Longitude: 95 to 141
+
+random.seed(42)
+
+
+def make_synthetic_indonesia(n_kab: int):
+    """Generate synthetic kabupaten dengan koordinat random di seluruh Indonesia."""
+    kabs = []
+    # Distribusi IPM Indonesia: range ~50-85, mean ~71
+    # Berdasarkan BPS 2024: Papua-NTT-Maluku tier rendah (50-65),
+    # Jawa-Bali tier menengah-tinggi (70-85), Sumatra mixed
+    for i in range(n_kab):
+        # IPM distribution skewed towards 65-78 (most kabs)
+        ipm = random.gauss(71, 8)
+        ipm = max(50, min(86, ipm))
+        # Random lat/lon dalam wilayah Indonesia
+        lat = random.uniform(-11.0, 6.0)
+        lon = random.uniform(95.0, 141.0)
+        # 18% Tier 1 (90 kota IHK / 514 kab)
+        tier = Tier.HIGH if random.random() < 0.18 else Tier.MEDIUM
+        kabs.append(Kabupaten(
+            id=f"{i:04d}", nama=f"Kab-{i}",
+            latitude=lat, longitude=lon, ipm=round(ipm, 2),
+            tier=tier, population=random.randint(100_000, 3_000_000),
+        ))
+    return kabs
+
+
+def make_workload(kabs, n_commodities: int, surplus_ratio: float = 0.5):
+    """Build supply + demand workload dari kabs untuk n komoditas."""
+    komos = [
+        Commodity(code=c, nama=n, max_distance_km=md, min_viable_tons=mv,
+                  max_fresh_age_days=mf)
+        for c, n, md, mv, mf, _ in KOMODITAS_DATA[:n_commodities]
+    ]
+    surplus, demand = [], []
+    for komo in komos:
+        for kab in kabs:
+            if random.random() < surplus_ratio:
+                surplus.append(SupplyNode(
+                    kabupaten=kab, commodity=komo,
+                    volume_tons=max(komo.min_viable_tons * 5,
+                                    random.uniform(10, 200)),
+                    price_per_kg=random.uniform(20000, 50000),
+                    harvest_age_days=random.randint(0, 3),
+                ))
+            else:
+                demand.append(DemandNode(
+                    kabupaten=kab, commodity=komo,
+                    volume_tons=max(komo.min_viable_tons * 4,
+                                    random.uniform(10, 150)),
+                    price_per_kg=random.uniform(40000, 80000),
+                ))
+    return surplus, demand
+
+
+def bench(label, surplus, demand, iterations: int = 10):
+    logistics = LogisticsContext()
+    samples = []
+    n_matches = 0
+    candidate_pairs = 0
+
+    for _ in range(iterations):
+        t = time.perf_counter()
+        report = run_matching(surplus, demand, logistics=logistics)
+        elapsed_ms = (time.perf_counter() - t) * 1000
+        samples.append(elapsed_ms)
+        n_matches = len(report.matches)
+        candidate_pairs = report.run_metadata.get("candidate_pairs_evaluated", 0)
+
+    return {
+        "label": label,
+        "n_supply": len(surplus),
+        "n_demand": len(demand),
+        "n_matches": n_matches,
+        "candidate_pairs": candidate_pairs,
+        "p50_ms": percentile(samples, 0.50),
+        "p95_ms": percentile(samples, 0.95),
+        "p99_ms": percentile(samples, 0.99),
+        "min_ms": min(samples),
+        "max_ms": max(samples),
+        "mean_ms": statistics.mean(samples),
+    }
+
+
+def print_result(r):
+    over_target = " ⚠ OVER 500ms" if r["p99_ms"] > 500 else ""
+    print(f"\n{r['label']}")
+    print(f"  Workload: {r['n_supply']} supply × {r['n_demand']} demand")
+    print(f"  Matches generated: {r['n_matches']}")
+    print(f"  Candidate pairs evaluated: {r['candidate_pairs']:,}")
+    print(f"  Latency: p50={r['p50_ms']:.1f}ms  p95={r['p95_ms']:.1f}ms  "
+          f"p99={r['p99_ms']:.1f}ms  max={r['max_ms']:.1f}ms{over_target}")
+
+
+def main():
+    print("=" * 90)
+    print(f"  NATIONAL SCALE STRESS TEST  ({datetime.now().strftime('%Y-%m-%d %H:%M:%S')})")
+    print("=" * 90)
+    print("  Target: <500ms p99 (Section 5.5.4)")
+    print("  Indonesia reality: 514 kab/kota × 19 komoditas")
+
+    configs = [
+        ("Provinsi (38 kab × 19 komoditas) — baseline Jatim", 38, 19),
+        ("Multi-provinsi (100 kab × 19)", 100, 19),
+        ("Setengah Indonesia (250 kab × 19)", 250, 19),
+        ("Full Indonesia (514 kab × 19) — TARGET NASIONAL", 514, 19),
+        ("Stress over-scale (1000 kab × 19)", 1000, 19),
+    ]
+
+    results = []
+    for label, n_kab, n_komo in configs:
+        kabs = make_synthetic_indonesia(n_kab)
+        surplus, demand = make_workload(kabs, n_komo)
+        # Reduced iterations for large workloads
+        iters = 20 if n_kab <= 100 else 5 if n_kab <= 514 else 3
+        r = bench(label, surplus, demand, iterations=iters)
+        results.append(r)
+        print_result(r)
+
+    print()
+    print("=" * 90)
+    print("  CONCLUSION")
+    print("=" * 90)
+    national = results[3]  # 514 kab
+    if national["p99_ms"] < 500:
+        print(f"  ✅ National scale 514 kab × 19 komoditas: p99 = "
+              f"{national['p99_ms']:.1f}ms — UNDER 500ms target. SIAP NASIONAL.")
+    else:
+        scale_factor = national["p99_ms"] / 500
+        print(f"  ⚠ National scale 514 kab × 19 komoditas: p99 = "
+              f"{national['p99_ms']:.1f}ms — OVER 500ms target")
+        print(f"     Slowdown vs target: {scale_factor:.1f}x — butuh optimization")
+        print(f"     Optimization yang dapat dipertimbangkan:")
+        print(f"       1. Spatial indexing (R-tree / geohash) di Layer 1")
+        print(f"       2. Pre-computed distance matrix (cached)")
+        print(f"       3. Per-province batching (decompose ke 38 sub-problems)")
+        print(f"       4. Parallel processing per komoditas (independent)")
+
+
+if __name__ == "__main__":
+    main()

benchmarks/output/equity_comparison.md

@@ -0,0 +1,41 @@
+# AgriFlow Equity Comparison
+
+Generated by `benchmarks/equity_comparison.py`.
+
+## Table 1 — Baseline Comparison (5 strategies)
+
+Coverage = volume-weighted tons fulfilled / tons demanded.  
+Gini / Atkinson = weighted by demand volume; lower = more equitable.  
+MinFulfill = fulfillment ratio of worst-served demand node; higher = better.  
+Sampang=3527 (IPM 66.72), Bangkalan=3526 (IPM 67.70).  
+
+| Strategy          | Coverage | Gini  | Atk(0.5) | Atk(1.0) | MinFulfill | Sampang | Bangkalan |
+|-------------------|----------|-------|----------|----------|-----------|---------|-----------|
+| pure_greedy       | 0.8897   | 0.0926| 0.0154   | 0.1126   | 0.0000    | 1.0000 | 1.0000    |
+| agriflow          | 0.8802   | 0.0990| 0.0162   | 0.1139   | 0.0000    | 1.0000 | 1.0000    |
+| uniform           | 0.9925   | 0.0075| 0.0054   | 0.0940   | 0.0000    | 1.0000 | 1.0000    |
+| proportional      | 0.9930   | 0.0070| 0.0053   | 0.0940   | 0.0000    | 1.0000 | 1.0000    |
+| agriflow_smoothed | 0.8802   | 0.0990| 0.0162   | 0.1139   | 0.0000    | 1.0000 | 1.0000    |
+
+## Table 2 — Action 6 Sensitivity (threshold variants)
+
+`current` delegates to `equity_multiplier_value` — single source of truth.
+
+| Variant | Coverage | Gini  | Sampang | Bangkalan | Description |
+|---------|----------|-------|---------|-----------|-------------|
+| strict  | 0.8802   | 0.0990| 1.0000 | 1.0000    | IPM <65→1.50, <70→1.25, <75→1.10, >=75→1.00 |
+| current | 0.8802   | 0.0990| 1.0000 | 1.0000    | IPM <68→1.30, <72→1.15, <78→1.05, >=78→1.00 [PROD] |
+| lenient | 0.8802   | 0.0990| 1.0000 | 1.0000    | IPM <70→1.15, <75→1.08, <80→1.03, >=80→1.00 |
+
+## Boundary Perturbation
+
+Shift all IPM thresholds simultaneously by ±1 or ±2 points.
+Counts kabupaten in Jatim (38 total) that move to a different tier.
+
+| Threshold shift | Kabs changing tier |
+|-----------------|---------------------|
+| -2 pts          | 10                  |
+| -1 pts          |  6                  |
+| +1 pts          |  2                  |
+| +2 pts          | 12                  |
+

benchmarks/output/equity_comparison_constrained.md

@@ -0,0 +1,99 @@
+# AgriFlow Equity Comparison — ABUNDANT vs CONSTRAINED
+
+Generated by `benchmarks/equity_comparison_constrained.py`.
+
+## Scenario: La Nina Supply Shock (CONSTRAINED)
+
+**Narasi:** La Nina banjir besar menghantam tiga sentra beras utama Jatim
+bagian barat — Ngawi (3521), Madiun (3519), Bojonegoro (3522) — secara
+bersamaan. Ketiga kab berada di dataran rendah lembah Bengawan Solo dan
+anak sungainya; pola banjir simultan terdokumentasi pada La Nina 2010,
+2020–21, dan 2022–23.
+
+**Dampak:** 6 surplus rows dihapus:
+
+| Kab | Nama | Komoditas | Volume (t) |
+|-----|------|-----------|------------|
+| 3521 | Ngawi | beras_premium | 500 |
+| 3521 | Ngawi | beras_medium | 900 |
+| 3521 | Ngawi | jagung | 600 |
+| 3519 | Madiun | beras_medium | 1200 |
+| 3522 | Bojonegoro | beras_premium | 650 |
+| 3522 | Bojonegoro | jagung | 800 |
+| **Total** | | | **4650** |
+
+**Arithmetic:**
+
+| Scenario | Surplus (t) | Deficit (t) | Ratio |
+|----------|-------------|-------------|-------|
+| ABUNDANT    | 8612 | 5249 | 1.641 (over-supplied) |
+| CONSTRAINED | 3962 | 5249 | 0.754 (under-supplied by 32.5%) |
+
+Fixture: `sample_data/surplus_deficit_constrained.csv` (committed).
+
+---
+
+## Table 1A — Baseline Comparison: ABUNDANT
+
+Coverage = volume-weighted tons fulfilled / tons demanded.  
+Gini / Atkinson = weighted by demand volume; lower = more equitable.  
+MinFulfill = fulfillment ratio of worst-served demand node.  
+Sampang=3527 (IPM 66.72), Bangkalan=3526 (IPM 67.70).  
+
+### ABUNDANT (surplus=8612t, deficit=5249t, ratio=1.641)
+
+| Strategy          | Coverage | Gini  | Atk(0.5) | Atk(1.0) | MinFulfill | Sampang | Bangkalan |
+|-------------------|----------|-------|----------|----------|-----------|---------|-----------|
+| pure_greedy       | 0.8897   | 0.0926| 0.0154   | 0.1126   | 0.0000    | 1.0000 | 1.0000    |
+| agriflow          | 0.8802   | 0.0990| 0.0162   | 0.1139   | 0.0000    | 1.0000 | 1.0000    |
+| uniform           | 0.9925   | 0.0075| 0.0054   | 0.0940   | 0.0000    | 1.0000 | 1.0000    |
+| proportional      | 0.9930   | 0.0070| 0.0053   | 0.0940   | 0.0000    | 1.0000 | 1.0000    |
+| agriflow_smoothed | 0.8802   | 0.0990| 0.0162   | 0.1139   | 0.0000    | 1.0000 | 1.0000    |
+
+## Table 1C — Baseline Comparison: CONSTRAINED
+
+Same metrics. Under supply shortage, equity tradeoffs become observable.
+
+### CONSTRAINED / La Nina banjir Ngawi+Madiun+Bojonegoro (surplus=3962t, deficit=5249t, ratio=0.754)
+
+| Strategy          | Coverage | Gini  | Atk(0.5) | Atk(1.0) | MinFulfill | Sampang | Bangkalan |
+|-------------------|----------|-------|----------|----------|-----------|---------|-----------|
+| pure_greedy       | 0.6649   | 0.3017| 0.2283   | 0.9840   | 0.0000    | 0.0000 | 0.2000    |
+| agriflow          | 0.6649   | 0.2905| 0.1764   | 0.9379   | 0.0000    | 1.0000 | 1.0000    |
+| uniform           | 0.6267   | 0.2522| 0.0575   | 0.1857   | 0.0000    | 1.0000 | 1.0000    |
+| proportional      | 0.7015   | 0.1589| 0.0290   | 0.1373   | 0.0000    | 0.7750 | 0.7750    |
+| agriflow_smoothed | 0.6649   | 0.2541| 0.1514   | 0.9333   | 0.0000    | 1.0000 | 1.0000    |
+
+## Table 2A — Sensitivity: ABUNDANT (degenerate — included for completeness)
+
+### Sensitivity ABUNDANT
+
+| Variant | Coverage | Gini  | MinFull | Sampang | Bangkalan | Description |
+|---------|----------|-------|---------|---------|-----------|-------------|
+| strict  | 0.8802   | 0.0990| 0.0000 | 1.0000 | 1.0000    | IPM <65->1.50, <70->1.25, <75->1.10, >=75->1.00 |
+| current | 0.8802   | 0.0990| 0.0000 | 1.0000 | 1.0000    | IPM <68->1.30, <72->1.15, <78->1.05, >=78->1.00 [PROD] |
+| lenient | 0.8802   | 0.0990| 0.0000 | 1.0000 | 1.0000    | IPM <70->1.15, <75->1.08, <80->1.03, >=80->1.00 |
+
+## Table 2C — Sensitivity: CONSTRAINED
+
+`current` delegates to `equity_multiplier_value` — single source of truth.
+
+### Sensitivity CONSTRAINED
+
+| Variant | Coverage | Gini  | MinFull | Sampang | Bangkalan | Description |
+|---------|----------|-------|---------|---------|-----------|-------------|
+| strict  | 0.6649   | 0.2905| 0.0000 | 1.0000 | 1.0000    | IPM <65->1.50, <70->1.25, <75->1.10, >=75->1.00 |
+| current | 0.6649   | 0.2905| 0.0000 | 1.0000 | 1.0000    | IPM <68->1.30, <72->1.15, <78->1.05, >=78->1.00 [PROD] |
+| lenient | 0.6649   | 0.2905| 0.0000 | 1.0000 | 1.0000    | IPM <70->1.15, <75->1.08, <80->1.03, >=80->1.00 |
+
+## Boundary Perturbation
+
+Same 38 Jatim kabs in both scenarios. Scenario-independent.
+
+| Threshold shift | Kabs changing tier |
+|-----------------|---------------------|
+| -2 pts          | 10                  |
+| -1 pts          |  6                  |
+| +1 pts          |  2                  |
+| +2 pts          | 12                  |
+

dashboard/.env.example

@@ -0,0 +1,26 @@
+# Copy to .env.local for dev (gitignored).
+# In Vercel: set NEXT_PUBLIC_API_URL in the project settings → Environment Variables.
+
+# Dev (FastAPI running locally on port 8000)
+NEXT_PUBLIC_API_URL=http://localhost:8000
+
+# Production (your Render service URL — copy from the Render dashboard after the
+# first deploy lands)
+# NEXT_PUBLIC_API_URL=https://agriflow-api.onrender.com
+
+# --- Auth (optional) --------------------------------------------------------
+# Supabase Auth powers the /login and /account pages. Leave BOTH unset to run
+# the dashboard with no login at all: the public map still works and the sign-in
+# button is hidden. Set both to enable accounts.
+# NEXT_PUBLIC_SUPABASE_URL=https://xxxxxxxx.supabase.co
+# NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGci...
+
+# --- Development login (LOCAL ONLY) -----------------------------------------
+# A hardcoded admin/admin login for testing the signed-in UI before Supabase
+# is wired up. Set NEXT_PUBLIC_DEV_LOGIN=true ONLY in .env.local for local dev.
+# NEVER set it in the Vercel production environment — it would let anyone in as
+# "admin". Left unset here on purpose; a production build with the flag absent
+# compiles the dev-login code out entirely.
+# NEXT_PUBLIC_DEV_LOGIN=true
+# NEXT_PUBLIC_DEV_EMAIL=admin
+# NEXT_PUBLIC_DEV_PASSWORD=admin

dashboard/.gitignore

@@ -0,0 +1,44 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+.vercel

dashboard/AGENTS.md

@@ -0,0 +1,5 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->

dashboard/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

dashboard/app/account/page.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+// Protected account page: shows the signed-in dashboard user and lets them
+// look up the plan attached to a WhatsApp number.
+//
+// The two identities are deliberately separate for now — a dinas account on the
+// dashboard and a farmer's WhatsApp subscription are different things. The
+// subscriber.dashboard_user_id column exists to link them when that is wanted.
+
+import { useEffect, useState } from "react";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { api, type BillingStatus } from "../lib/api";
+import { useAuth } from "../lib/auth";
+
+export default function AccountPage() {
+  const { user, loading, configured, signOut } = useAuth();
+  const router = useRouter();
+
+  const [phone, setPhone] = useState("");
+  const [status, setStatus] = useState<BillingStatus | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    // Only bounce once we know the session state, or a signed-in user gets
+    // kicked to /login on every refresh while the session is still resolving.
+    if (!loading && !user && configured) router.replace("/login");
+  }, [loading, user, configured, router]);
+
+  if (loading) {
+    return <main className="flex-1 grid place-items-center text-slate-500">Memuat…</main>;
+  }
+
+  if (!configured) {
+    return (
+      <main className="flex-1 p-6 max-w-2xl mx-auto">
+        <Link href="/" className="text-sm text-slate-500 hover:text-slate-800">← Kembali ke peta</Link>
+        <p className="mt-6 rounded-lg bg-amber-50 border border-amber-200 p-4 text-sm text-amber-900">
+          Login belum dikonfigurasi di lingkungan ini.
+        </p>
+      </main>
+    );
+  }
+
+  if (!user) return null; // redirect in flight
+
+  async function lookup(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    setStatus(null);
+    setBusy(true);
+    try {
+      setStatus(await api.billingStatus(phone));
+    } catch {
+      setError("Nomor tidak valid atau layanan sedang tidak tersedia.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <main className="flex-1 p-6 max-w-2xl mx-auto w-full">
+      <Link href="/" className="text-sm text-slate-500 hover:text-slate-800">← Kembali ke peta</Link>
+
+      <h1 className="mt-6 text-2xl font-semibold text-slate-900">Akun</h1>
+
+      <section className="mt-4 rounded-xl border border-slate-200 bg-white p-5">
+        <p className="text-sm text-slate-500">Masuk sebagai</p>
+        <p className="font-medium text-slate-900">{user.email}</p>
+        <button
+          onClick={async () => { await signOut(); router.push("/"); }}
+          className="mt-4 rounded-lg border border-slate-300 px-4 py-2 text-sm font-medium
+                     text-slate-700 hover:bg-slate-50"
+        >
+          Keluar
+        </button>
+      </section>
+
+      <section className="mt-6 rounded-xl border border-slate-200 bg-white p-5">
+        <h2 className="font-semibold text-slate-900">Langganan WhatsApp</h2>
+        <p className="mt-1 text-sm text-slate-500">
+          Cek paket dan sisa kuota untuk sebuah nomor WhatsApp. Nomor di-hash di
+          server dan tidak disimpan dalam bentuk aslinya.
+        </p>
+
+        <form onSubmit={lookup} className="mt-4 flex gap-2">
+          <input
+            type="tel"
+            required
+            placeholder="+628123456789"
+            value={phone}
+            onChange={(e) => setPhone(e.target.value)}
+            className="flex-1 rounded-lg border border-slate-300 px-3 py-2 text-sm
+                       focus:border-emerald-600 focus:outline-none focus:ring-1 focus:ring-emerald-600"
+          />
+          <button
+            type="submit"
+            disabled={busy}
+            className="rounded-lg bg-emerald-700 px-4 py-2 text-sm font-medium text-white
+                       hover:bg-emerald-800 disabled:opacity-50"
+          >
+            {busy ? "…" : "Cek"}
+          </button>
+        </form>
+
+        {error && (
+          <p role="alert" className="mt-3 rounded-lg bg-red-50 border border-red-200 p-3 text-sm text-red-800">
+            {error}
+          </p>
+        )}
+
+        {status && (
+          <dl className="mt-4 grid grid-cols-2 gap-x-4 gap-y-2 text-sm">
+            <dt className="text-slate-500">Paket</dt>
+            <dd className="font-medium text-slate-900">
+              {status.is_pro ? "PRO" : "GRATIS"}
+            </dd>
+
+            <dt className="text-slate-500">Kuota hari ini</dt>
+            <dd className="font-medium text-slate-900">
+              {status.is_pro
+                ? "Tanpa batas"
+                : `${status.used_today} dari ${status.limit} terpakai`}
+            </dd>
+
+            {status.expires_at && (
+              <>
+                <dt className="text-slate-500">Aktif sampai</dt>
+                <dd className="font-medium text-slate-900">
+                  {new Date(status.expires_at).toLocaleDateString("id-ID", {
+                    day: "numeric", month: "long", year: "numeric",
+                  })}
+                </dd>
+              </>
+            )}
+          </dl>
+        )}
+      </section>
+    </main>
+  );
+}

dashboard/app/components/AccountMenu.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+// Account affordance for the dashboard header.
+//
+// The site is login-first (see proxy.ts), so by the time a page renders the
+// visitor is always either a real signed-in user or a guest. This menu shows
+// which, and gives each a way out:
+//   - real user  -> account link (email), sign-out lives on /account
+//   - guest      -> a "Tamu" chip plus "Keluar" to drop the guest cookie and
+//                   return to /login, where they can sign in for real
+
+import Link from "next/link";
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { useAuth } from "../lib/auth";
+import { exitGuest, isGuest } from "../lib/guest";
+
+export default function AccountMenu() {
+  const { user, loading } = useAuth();
+  const router = useRouter();
+
+  // The guest cookie is not reactive, so read it once on mount. Client-only:
+  // isGuest() returns false during SSR, which is fine (the menu is decorative).
+  const [guest, setGuest] = useState(false);
+  useEffect(() => setGuest(isGuest()), []);
+
+  if (loading) return null;
+
+  if (user) {
+    return (
+      <Link
+        href="/account"
+        className="flex items-center gap-2 rounded-lg border border-slate-300 px-3 py-1.5
+                   text-sm font-medium text-slate-700 hover:bg-slate-50"
+        title={user.email ?? undefined}
+      >
+        <span
+          aria-hidden
+          className="grid h-6 w-6 place-items-center rounded-full bg-emerald-700 text-xs text-white"
+        >
+          {(user.email ?? "?").charAt(0).toUpperCase()}
+        </span>
+        <span className="max-w-[12ch] truncate">{user.email}</span>
+      </Link>
+    );
+  }
+
+  if (guest) {
+    return (
+      <div className="flex items-center gap-2">
+        <span className="rounded-full bg-slate-100 px-2.5 py-1 text-xs font-medium text-slate-500">
+          Mode Tamu
+        </span>
+        <button
+          onClick={() => {
+            exitGuest();
+            router.push("/login");
+          }}
+          className="rounded-lg border border-slate-300 px-3 py-1.5 text-sm font-medium
+                     text-slate-700 hover:bg-slate-50"
+        >
+          Keluar
+        </button>
+      </div>
+    );
+  }
+
+  // Fallback (e.g. brief pre-hydration flash): offer the way in.
+  return (
+    <Link
+      href="/login"
+      className="rounded-lg border border-slate-300 px-3 py-1.5 text-sm font-medium
+                 text-slate-700 hover:bg-slate-50"
+    >
+      Masuk
+    </Link>
+  );
+}

dashboard/app/components/AnomalyPanel.tsx

@@ -0,0 +1,155 @@
+"use client";
+
+/**
+ * AnomalyPanel — displays recent price anomalies (S-H-ESD detections).
+ *
+ * Shows a scrollable list of anomalies with SPIKE/DROP badges,
+ * deviation percentage, and city/commodity labels.
+ *
+ * Props:
+ *   anomalies   AnomalyRecord[]
+ *   loading     boolean
+ *   error       string | null
+ *   totalCount  number
+ */
+
+import type { AnomalyRecord } from "../lib/api";
+
+// ---------------------------------------------------------------------------
+// Format helpers
+// ---------------------------------------------------------------------------
+
+function fmtIdr(n: number): string {
+  if (n >= 1_000_000) return "Rp " + (n / 1_000_000).toFixed(2) + "jt";
+  if (n >= 1_000)     return "Rp " + (n / 1_000).toFixed(1) + "k";
+  return "Rp " + n.toFixed(0);
+}
+
+function fmtDate(iso: string): string {
+  const d = new Date(iso);
+  return d.toLocaleDateString("id-ID", { day: "numeric", month: "short", year: "numeric" });
+}
+
+const COMMODITY_NAMES: Record<string, string> = {
+  cabai_rawit:   "Cabai Rawit",
+  bawang_merah:  "Bawang Merah",
+  bawang_putih:  "Bawang Putih",
+  beras_medium:  "Beras Medium",
+  beras_premium: "Beras Premium",
+  daging_ayam:   "Daging Ayam",
+  telur_ayam:    "Telur Ayam",
+};
+
+// ---------------------------------------------------------------------------
+// Single anomaly row
+// ---------------------------------------------------------------------------
+
+function AnomalyRow({ a }: { a: AnomalyRecord }) {
+  const isSpike = a.type === "SPIKE";
+  const sign    = a.deviation_pct >= 0 ? "+" : "";
+  const comName = COMMODITY_NAMES[a.commodity_code] ?? a.commodity_code;
+
+  return (
+    <li className="px-3 py-2 hover:bg-zinc-50 flex items-start gap-2.5">
+      {/* Badge */}
+      <span
+        className={`text-[10px] font-bold px-1.5 py-0.5 rounded whitespace-nowrap mt-0.5 ${
+          isSpike
+            ? "bg-rose-100 text-rose-700"
+            : "bg-sky-100 text-sky-700"
+        }`}
+      >
+        {a.type}
+      </span>
+
+      {/* Content */}
+      <div className="flex-1 min-w-0">
+        <div className="flex items-baseline justify-between gap-1">
+          <span className="text-xs font-medium text-zinc-800 truncate">{comName}</span>
+          <span className={`text-xs font-mono ${isSpike ? "text-rose-600" : "text-sky-600"}`}>
+            {sign}{a.deviation_pct.toFixed(1)}%
+          </span>
+        </div>
+        <div className="text-[11px] text-zinc-500 mt-0.5">
+          {fmtDate(a.date)} · {a.city_name} · {fmtIdr(a.price)}/kg
+        </div>
+        <div className="text-[10px] text-zinc-400 mt-0.5">
+          score {a.score.toFixed(2)}
+          {a.persistent && (
+            <span className="ml-1.5 text-indigo-500">persisten</span>
+          )}
+        </div>
+      </div>
+    </li>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main panel
+// ---------------------------------------------------------------------------
+
+type Props = {
+  anomalies:  AnomalyRecord[];
+  loading:    boolean;
+  error:      string | null;
+  totalCount: number;
+};
+
+export default function AnomalyPanel({ anomalies, loading, error, totalCount }: Props) {
+  if (error) {
+    return (
+      <div className="border border-rose-200 rounded-lg p-3 bg-rose-50 text-xs text-rose-700">
+        {error}
+      </div>
+    );
+  }
+
+  return (
+    <div className="border border-zinc-200 rounded-lg bg-white overflow-hidden">
+      {/* Header */}
+      <div className="px-3 py-2 border-b border-zinc-100 flex items-center justify-between">
+        <span className="text-xs font-semibold text-zinc-800">
+          Anomali Harga Terbaru
+        </span>
+        <span className="text-[10px] text-zinc-400">
+          {loading ? "memuat..." : `${totalCount.toLocaleString("id-ID")} total`}
+        </span>
+      </div>
+
+      {loading && (
+        <div className="px-3 py-4 text-xs text-zinc-400 animate-pulse">
+          Memuat anomali...
+        </div>
+      )}
+
+      {!loading && anomalies.length === 0 && (
+        <div className="px-3 py-4 text-xs text-zinc-400">
+          Tidak ada anomali untuk filter ini.
+        </div>
+      )}
+
+      {!loading && anomalies.length > 0 && (
+        <>
+          <ul className="divide-y divide-zinc-100 max-h-64 overflow-y-auto">
+            {anomalies.map((a, i) => (
+              <AnomalyRow key={`${a.date}-${a.commodity_code}-${a.city_id}-${i}`} a={a} />
+            ))}
+          </ul>
+
+          {/* Legend */}
+          <div className="px-3 py-1.5 border-t border-zinc-100 flex gap-3 text-[10px] text-zinc-500">
+            <span className="flex items-center gap-1">
+              <span className="w-2 h-2 rounded-sm bg-rose-200 inline-block" />
+              SPIKE (harga naik)
+            </span>
+            <span className="flex items-center gap-1">
+              <span className="w-2 h-2 rounded-sm bg-sky-200 inline-block" />
+              DROP (harga turun)
+            </span>
+            <span className="ml-1 text-indigo-400">persisten = ≥2 hari beruntun</span>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

dashboard/app/components/ForecastPanel.tsx

@@ -0,0 +1,258 @@
+"use client";
+
+/**
+ * ForecastPanel — 30-day price forecast chart + CI band.
+ *
+ * Renders a lightweight SVG line chart (no external charting lib) consistent
+ * with the existing dashboard aesthetic.  The CI band (P10-P90) is rendered as
+ * a filled area; the point forecast is a line; history end date is marked.
+ *
+ * Props:
+ *   forecast      ForecastResponse | null  — null while loading
+ *   loading       boolean
+ *   error         string | null
+ */
+
+import { useMemo } from "react";
+import type { ForecastPoint, ForecastResponse } from "../lib/api";
+
+// ---------------------------------------------------------------------------
+// Format helpers
+// ---------------------------------------------------------------------------
+
+function fmtIdr(n: number): string {
+  if (n >= 1_000_000) return "Rp " + (n / 1_000_000).toFixed(1) + "jt";
+  if (n >= 1_000)     return "Rp " + (n / 1_000).toFixed(0) + "k";
+  return "Rp " + n.toFixed(0);
+}
+
+function fmtDate(iso: string): string {
+  const d = new Date(iso);
+  return d.toLocaleDateString("id-ID", { day: "numeric", month: "short" });
+}
+
+// ---------------------------------------------------------------------------
+// SVG chart
+// ---------------------------------------------------------------------------
+
+const CHART_W  = 520;
+const CHART_H  = 160;
+const PAD_L    = 52;
+const PAD_R    = 16;
+const PAD_T    = 12;
+const PAD_B    = 28;
+
+type ChartProps = {
+  forecasts: ForecastPoint[];
+};
+
+function ForecastChart({ forecasts }: ChartProps) {
+  const plotW = CHART_W - PAD_L - PAD_R;
+  const plotH = CHART_H - PAD_T - PAD_B;
+
+  const { minP, maxP, xScale, yScale, bandPath, linePath, ticks } =
+    useMemo(() => {
+      const all = forecasts.flatMap((pt) => [pt.p10, pt.p90]);
+      const minP = Math.min(...all);
+      const maxP = Math.max(...all);
+      const pad  = (maxP - minP) * 0.1 || 1000;
+      const lo   = minP - pad;
+      const hi   = maxP + pad;
+      const n    = forecasts.length;
+
+      const xScale = (i: number) => PAD_L + (i / (n - 1)) * plotW;
+      const yScale = (v: number) => PAD_T + plotH - ((v - lo) / (hi - lo)) * plotH;
+
+      // CI band (p10 → p90 reversed)
+      const fwd  = forecasts.map((pt, i) => `${xScale(i)},${yScale(pt.p90)}`).join(" ");
+      const bwd  = [...forecasts].reverse().map((pt, i) =>
+        `${xScale(n - 1 - i)},${yScale(pt.p10)}`
+      ).join(" ");
+      const bandPath = `M ${fwd} L ${bwd} Z`;
+
+      // Point forecast line
+      const linePath = "M " + forecasts
+        .map((pt, i) => `${xScale(i)},${yScale(pt.point)}`)
+        .join(" L ");
+
+      // X-axis ticks: day 1, 8, 15, 22, 30
+      const tickIdxs = [0, 7, 14, 21, n - 1];
+      const ticks = tickIdxs.filter((i) => i < n).map((i) => ({
+        x:    xScale(i),
+        label: fmtDate(forecasts[i].date),
+      }));
+
+      // Y-axis ticks: 3 evenly spaced
+      const yTicks = [lo + (hi - lo) * 0.1, lo + (hi - lo) * 0.5, lo + (hi - lo) * 0.9];
+
+      return { minP, maxP, xScale, yScale, bandPath, linePath, ticks, yTicks };
+    }, [forecasts]);
+
+  const yTickVals = useMemo(() => {
+    const all = forecasts.flatMap((pt) => [pt.p10, pt.p90]);
+    const lo   = Math.min(...all) - (Math.max(...all) - Math.min(...all)) * 0.1;
+    const hi   = Math.max(...all) + (Math.max(...all) - Math.min(...all)) * 0.1;
+    return [
+      lo + (hi - lo) * 0.1,
+      lo + (hi - lo) * 0.5,
+      lo + (hi - lo) * 0.9,
+    ].map((v) => ({
+      y:     PAD_T + CHART_H - PAD_T - PAD_B - ((v - lo) / (hi - lo)) * (CHART_H - PAD_T - PAD_B),
+      label: fmtIdr(v),
+    }));
+  }, [forecasts]);
+
+  return (
+    <svg
+      viewBox={`0 0 ${CHART_W} ${CHART_H}`}
+      className="w-full"
+      style={{ height: CHART_H }}
+    >
+      {/* Y grid lines + labels */}
+      {yTickVals.map((t, i) => (
+        <g key={i}>
+          <line
+            x1={PAD_L} y1={t.y} x2={CHART_W - PAD_R} y2={t.y}
+            stroke="#e4e4e7" strokeWidth={1}
+          />
+          <text
+            x={PAD_L - 4} y={t.y + 4}
+            textAnchor="end"
+            fontSize={9}
+            fill="#71717a"
+          >
+            {t.label}
+          </text>
+        </g>
+      ))}
+
+      {/* CI band */}
+      <path d={bandPath} fill="#6366f1" fillOpacity={0.12} />
+
+      {/* Point forecast line */}
+      <path
+        d={linePath}
+        fill="none"
+        stroke="#6366f1"
+        strokeWidth={2}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+
+      {/* X-axis ticks */}
+      {ticks.map((t) => (
+        <g key={t.x}>
+          <line
+            x1={t.x} y1={CHART_H - PAD_B} x2={t.x} y2={CHART_H - PAD_B + 4}
+            stroke="#a1a1aa" strokeWidth={1}
+          />
+          <text
+            x={t.x} y={CHART_H - PAD_B + 13}
+            textAnchor="middle"
+            fontSize={9}
+            fill="#71717a"
+          >
+            {t.label}
+          </text>
+        </g>
+      ))}
+
+      {/* X axis line */}
+      <line
+        x1={PAD_L} y1={CHART_H - PAD_B}
+        x2={CHART_W - PAD_R} y2={CHART_H - PAD_B}
+        stroke="#d4d4d8" strokeWidth={1}
+      />
+    </svg>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main panel
+// ---------------------------------------------------------------------------
+
+type Props = {
+  forecast: ForecastResponse | null;
+  loading:  boolean;
+  error:    string | null;
+};
+
+export default function ForecastPanel({ forecast, loading, error }: Props) {
+  if (error) {
+    return (
+      <div className="border border-rose-200 rounded-lg p-3 bg-rose-50 text-xs text-rose-700">
+        {error}
+      </div>
+    );
+  }
+
+  if (loading || !forecast) {
+    return (
+      <div className="border border-zinc-200 rounded-lg p-3 text-xs text-zinc-400 animate-pulse">
+        Memuat forecast...
+      </div>
+    );
+  }
+
+  const isBaseline = forecast.method === "seasonal_naive_baseline";
+  const first      = forecast.forecasts[0];
+  const last       = forecast.forecasts[forecast.forecasts.length - 1];
+
+  return (
+    <div className="border border-zinc-200 rounded-lg bg-white overflow-hidden">
+      {/* Header */}
+      <div className="px-3 py-2 border-b border-zinc-100 flex items-center justify-between">
+        <div>
+          <span className="text-xs font-semibold text-zinc-800">
+            Forecast 30 hari — {forecast.city_name}
+          </span>
+          <span className="ml-2 text-[10px] text-zinc-400">
+            s.d. {forecast.history_end_date}
+          </span>
+        </div>
+        {isBaseline && (
+          <span className="text-[10px] bg-amber-100 text-amber-800 px-1.5 py-0.5 rounded font-medium">
+            baseline statistik
+          </span>
+        )}
+      </div>
+
+      {/* Chart */}
+      <div className="px-2 pt-1">
+        <ForecastChart forecasts={forecast.forecasts} />
+      </div>
+
+      {/* Summary row */}
+      <div className="px-3 py-2 flex gap-4 text-[11px] border-t border-zinc-100">
+        <span className="text-zinc-500">
+          Hari 1 ({fmtDate(first.date)}):{" "}
+          <span className="font-semibold text-zinc-800">{fmtIdr(first.point)}/kg</span>
+        </span>
+        <span className="text-zinc-500">
+          Hari 30 ({fmtDate(last.date)}):{" "}
+          <span className="font-semibold text-zinc-800">{fmtIdr(last.point)}/kg</span>
+        </span>
+        <span className="text-zinc-400">
+          CI: {fmtIdr(last.p10)} – {fmtIdr(last.p90)}
+        </span>
+      </div>
+
+      {/* Legend */}
+      <div className="px-3 pb-2 flex gap-3 text-[10px] text-zinc-500">
+        <span className="flex items-center gap-1">
+          <span className="w-4 h-0.5 bg-indigo-500 inline-block" />
+          Point
+        </span>
+        <span className="flex items-center gap-1">
+          <span className="w-4 h-3 bg-indigo-400/20 border border-indigo-300/30 inline-block rounded-sm" />
+          P10–P90
+        </span>
+        {isBaseline && (
+          <span className="text-amber-600 ml-1">
+            * Seasonal-naive baseline, bukan TimesFM
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}

dashboard/app/components/MapView.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+import { MapContainer, TileLayer, CircleMarker, Tooltip, Polyline } from "react-leaflet";
+import "leaflet/dist/leaflet.css";
+import type { Kabupaten, SurplusDeficitRow, Match } from "../lib/api";
+
+const CENTER: [number, number] = [-7.7, 112.5]; // Jawa Timur centroid-ish
+const ZOOM = 8;
+
+type Props = {
+  kabupaten: Kabupaten[];
+  surplusDeficit: SurplusDeficitRow[];
+  matches: Match[];
+  onSelectKab: (kabId: string) => void;
+  selectedKabId: string | null;
+};
+
+// Radius proportional to sqrt(volume) so visual area ~ volume.
+function bubbleRadius(tons: number): number {
+  if (tons <= 0) return 4;
+  return Math.max(6, Math.min(28, Math.sqrt(tons) * 1.8));
+}
+
+export default function MapView({
+  kabupaten, surplusDeficit, matches, onSelectKab, selectedKabId,
+}: Props) {
+  const rowByKab = new Map<string, SurplusDeficitRow>();
+  for (const r of surplusDeficit) rowByKab.set(r.kab_id, r);
+
+  return (
+    <MapContainer
+      center={CENTER}
+      zoom={ZOOM}
+      scrollWheelZoom
+      style={{ height: "100%", width: "100%" }}
+    >
+      <TileLayer
+        attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>'
+        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
+      />
+
+      {/* Flow lines for top matches */}
+      {matches.slice(0, 10).map((m, idx) => (
+        <Polyline
+          key={`flow-${idx}`}
+          positions={[
+            [m.surplus.lat, m.surplus.lng],
+            [m.deficit.lat, m.deficit.lng],
+          ]}
+          pathOptions={{
+            color: "#4e643c",
+            weight: 2,
+            opacity: 0.75,
+            dashArray: "5 5",
+          }}
+        />
+      ))}
+
+      {/* Kabupaten bubbles */}
+      {kabupaten.map((k) => {
+        const row = rowByKab.get(k.id);
+        const role = row?.role;
+        const tons = row?.volume_tons ?? 0;
+        const color =
+          role === "surplus" ? "#16a34a"
+          : role === "deficit" ? "#dc2626"
+          : "#94a3b8";
+        const radius = row ? bubbleRadius(tons) : 4;
+        const isSelected = selectedKabId === k.id;
+        return (
+          <CircleMarker
+            key={k.id}
+            center={[k.lat, k.lng]}
+            radius={radius}
+            pathOptions={{
+              color: isSelected ? "#facc15" : color,
+              weight: isSelected ? 3 : 1.5,
+              fillColor: color,
+              fillOpacity: row ? 0.55 : 0.25,
+            }}
+            eventHandlers={{ click: () => onSelectKab(k.id) }}
+          >
+            <Tooltip direction="top" offset={[0, -4]}>
+              <div className="space-y-1 text-[11px] text-zinc-700 leading-normal">
+                <strong className="text-sm text-zinc-900 block border-b border-zinc-100 pb-0.5">{k.nama}</strong>
+                <div>Kategori Wilayah: <span className="font-semibold text-zinc-800">{k.tier.replace("TIER_", "").replace("_HIGH", " Tinggi").replace("_MEDIUM", " Sedang")}</span></div>
+                <div>IPM: <span className="font-semibold text-zinc-800">{k.ipm.toFixed(1)}</span></div>
+                <div>Jumlah Penduduk: <span className="font-semibold text-zinc-800">{k.population.toLocaleString("id-ID")} jiwa</span></div>
+                {row && (
+                  <div className="mt-1 pt-1 border-t border-dashed border-zinc-200">
+                    <span className="font-semibold" style={{ color }}>
+                      {role === "surplus" ? "Stok Berlebih (Surplus)" : "Kekurangan Stok (Defisit)"}: {tons.toFixed(0)} ton
+                    </span>
+                  </div>
+                )}
+              </div>
+            </Tooltip>
+          </CircleMarker>
+        );
+      })}
+    </MapContainer>
+  );
+}

dashboard/app/forgot-password/ForgotPasswordForm.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { useSearchParams } from "next/navigation";
+import { useAuth } from "../lib/auth";
+
+export default function ForgotPasswordForm() {
+  const { requestPasswordReset, configured } = useAuth();
+  const searchParams = useSearchParams();
+
+  const [email, setEmail] = useState(searchParams.get("email") ?? "");
+  const [error, setError] = useState<string | null>(null);
+  const [sent, setSent] = useState(false);
+  const [busy, setBusy] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    setBusy(true);
+    const { error } = await requestPasswordReset(email);
+    setBusy(false);
+
+    if (error) {
+      setError(error);
+      return;
+    }
+    // Supabase does not signal whether the address is registered, and we
+    // don't either — showing the same confirmation either way avoids
+    // leaking account existence through this form.
+    setSent(true);
+  }
+
+  return (
+    <main className="flex-1 flex items-center justify-center p-6 bg-slate-50">
+      <div className="w-full max-w-sm">
+        <Link href="/login" className="block text-sm text-slate-500 hover:text-slate-800 mb-6">
+          ← Kembali ke halaman masuk
+        </Link>
+
+        <h1 className="text-2xl font-semibold text-slate-900">Lupa kata sandi</h1>
+        <p className="mt-1 text-sm text-slate-500">
+          Masukkan email akun Anda. Kami akan mengirim tautan untuk mengatur
+          ulang kata sandi.
+        </p>
+
+        {!configured && (
+          <p className="mt-4 rounded-lg bg-amber-50 border border-amber-200 p-3 text-sm text-amber-900">
+            Login belum dikonfigurasi di lingkungan ini. Peta dan data tetap
+            dapat diakses tanpa masuk.
+          </p>
+        )}
+
+        {sent ? (
+          <p className="mt-6 rounded-lg bg-emerald-50 border border-emerald-200 p-3 text-sm text-emerald-900">
+            Jika email tersebut terdaftar, tautan atur ulang kata sandi sudah
+            dikirim. Periksa kotak masuk (dan folder spam) Anda.
+          </p>
+        ) : (
+          <form onSubmit={onSubmit} className="mt-6 space-y-4">
+            <div>
+              <label htmlFor="email" className="block text-sm font-medium text-slate-700">
+                Email
+              </label>
+              <input
+                id="email"
+                type="email"
+                required
+                autoComplete="email"
+                value={email}
+                onChange={(e) => setEmail(e.target.value)}
+                className="mt-1 w-full rounded-lg border border-slate-300 px-3 py-2 text-sm
+                           focus:border-emerald-600 focus:outline-none focus:ring-1 focus:ring-emerald-600"
+              />
+            </div>
+
+            {error && (
+              <p role="alert" className="rounded-lg bg-red-50 border border-red-200 p-3 text-sm text-red-800">
+                {error}
+              </p>
+            )}
+
+            <button
+              type="submit"
+              disabled={busy || !configured}
+              className="w-full rounded-lg bg-emerald-700 px-4 py-2.5 text-sm font-medium text-white
+                         hover:bg-emerald-800 disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              {busy ? "Mengirim…" : "Kirim tautan atur ulang"}
+            </button>
+          </form>
+        )}
+      </div>
+    </main>
+  );
+}

dashboard/app/forgot-password/page.tsx

@@ -0,0 +1,19 @@
+import { Suspense } from "react";
+import ForgotPasswordForm from "./ForgotPasswordForm";
+
+// ForgotPasswordForm reads ?email= via useSearchParams() to prefill the
+// field when arriving from the login page, which forces client-side
+// rendering for that subtree — same reason /login wraps LoginForm.
+export default function ForgotPasswordPage() {
+  return (
+    <Suspense
+      fallback={
+        <main className="flex-1 grid place-items-center text-slate-500">
+          Memuat…
+        </main>
+      }
+    >
+      <ForgotPasswordForm />
+    </Suspense>
+  );
+}

dashboard/app/globals.css

@@ -0,0 +1,36 @@
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap');
+@import "tailwindcss";
+
+:root {
+  --background: #5b7245;
+  --foreground: #171717;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: 'Inter', system-ui, -apple-system, sans-serif;
+}
+
+/* Custom scrollbars for clean dashboards */
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+::-webkit-scrollbar-thumb {
+  background: rgba(0, 0, 0, 0.15);
+  border-radius: 4px;
+}
+::-webkit-scrollbar-thumb:hover {
+  background: rgba(0, 0, 0, 0.25);
+}
+

dashboard/app/layout.tsx

@@ -0,0 +1,36 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+import { AuthProvider } from "./lib/auth";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "AgriFlow Dashboard",
+  description: "Surplus-defisit pangan Jawa Timur · matching engine live",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html
+      lang="en"
+      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
+    >
+      <body className="min-h-full flex flex-col">
+        <AuthProvider>{children}</AuthProvider>
+      </body>
+    </html>
+  );
+}

dashboard/app/lib/api.ts

@@ -0,0 +1,187 @@
+// Typed thin wrapper around the FastAPI dashboard endpoints.
+
+import { getSupabase } from "./supabase";
+
+const API_BASE =
+  process.env.NEXT_PUBLIC_API_URL?.replace(/\/$/, "") ||
+  "http://localhost:8000";
+
+export type Commodity = { code: string; nama: string };
+
+export type BillingStatus = {
+  plan: "FREE" | "PRO";
+  is_pro: boolean;
+  expires_at: string | null;
+  used_today: number;
+  limit: number;
+  remaining: number; // -1 means unlimited (PRO)
+};
+
+export type Kabupaten = {
+  id: string;
+  nama: string;
+  lat: number;
+  lng: number;
+  tier: string;
+  ipm: number;
+  population: number;
+};
+
+export type SurplusDeficitRow = {
+  kab_id: string;
+  kab_nama: string;
+  lat: number;
+  lng: number;
+  tier: string;
+  role: "surplus" | "deficit";
+  volume_tons: number;
+  price_per_kg: number;
+};
+
+export type SurplusDeficitResponse = {
+  commodity: { code: string; nama: string };
+  rows: SurplusDeficitRow[];
+  totals: { surplus_tons: number; deficit_tons: number; balance_tons: number };
+};
+
+export type Match = {
+  surplus: {
+    kab_id: string;
+    kab_nama: string;
+    lat: number;
+    lng: number;
+    price_per_kg: number;
+  };
+  deficit: {
+    kab_id: string;
+    kab_nama: string;
+    lat: number;
+    lng: number;
+    price_per_kg: number;
+  };
+  commodity_code: string;
+  commodity_nama: string;
+  matched_volume_tons: number;
+  distance_km: number;
+  final_score: number;
+  confidence: string;
+  flags: string[];
+};
+
+export type MatchesResponse = { count: number; matches: Match[] };
+
+// ---------------------------------------------------------------------------
+// Forecast types
+// ---------------------------------------------------------------------------
+
+export type ForecastPoint = {
+  date: string;   // ISO 8601
+  point: number;  // IDR/kg
+  p10: number;
+  p90: number;
+};
+
+export type ForecastResponse = {
+  commodity_code:   string;
+  city_id:          string;
+  city_name:        string;
+  method:           string;  // "timesfm_2.0" | "seasonal_naive_baseline"
+  generated_at:     string;
+  horizon_days:     number;
+  history_end_date: string;
+  forecasts:        ForecastPoint[];
+};
+
+// ---------------------------------------------------------------------------
+// Anomaly types
+// ---------------------------------------------------------------------------
+
+export type AnomalyRecord = {
+  date:           string;   // ISO 8601
+  price:          number;   // IDR/kg
+  rolling_median: number;
+  deviation_pct:  number;   // signed; positive = spike
+  type:           "SPIKE" | "DROP";
+  score:          number;
+  commodity_code: string;
+  city_id:        string;
+  city_name:      string;
+  persistent:     boolean;
+};
+
+export type AnomaliesResponse = {
+  count:     number;
+  method:    string;
+  anomalies: AnomalyRecord[];
+};
+
+// ---------------------------------------------------------------------------
+// Fetch helper + API object
+// ---------------------------------------------------------------------------
+
+// Thrown when the API rejects our token. Callers can catch this specifically
+// to send the user back to /login instead of showing a generic error.
+export class UnauthorizedError extends Error {
+  constructor(path: string) {
+    super(`${path} requires sign-in`);
+    this.name = "UnauthorizedError";
+  }
+}
+
+async function fetchJson<T>(path: string): Promise<T> {
+  const headers: Record<string, string> = {};
+
+  // Attach the Supabase access token when there is a session. getSession()
+  // refreshes it if it is close to expiry, so a tab left open overnight sends
+  // a live token rather than a stale one.
+  const supabase = getSupabase();
+  if (supabase) {
+    const { data } = await supabase.auth.getSession();
+    const token = data.session?.access_token;
+    if (token) headers.Authorization = `Bearer ${token}`;
+  }
+
+  const r = await fetch(`${API_BASE}${path}`, { cache: "no-store", headers });
+  if (r.status === 401) throw new UnauthorizedError(path);
+  if (!r.ok) throw new Error(`${path} failed: ${r.status}`);
+  return r.json() as Promise<T>;
+}
+
+export const api = {
+  commodities: () => fetchJson<Commodity[]>("/api/v1/commodities"),
+  kabupaten: () => fetchJson<Kabupaten[]>("/api/v1/kabupaten"),
+  surplusDeficit: (commodity: string) =>
+    fetchJson<SurplusDeficitResponse>(
+      `/api/v1/surplus-deficit?commodity=${encodeURIComponent(commodity)}`,
+    ),
+  matches: (params: { commodity?: string; kab_id?: string; limit?: number }) => {
+    const q = new URLSearchParams();
+    if (params.commodity) q.set("commodity", params.commodity);
+    if (params.kab_id) q.set("kab_id", params.kab_id);
+    if (params.limit) q.set("limit", String(params.limit));
+    return fetchJson<MatchesResponse>(`/api/v1/matches?${q.toString()}`);
+  },
+  forecast: (params: { commodity: string; city: string }) =>
+    fetchJson<ForecastResponse>(
+      `/api/v1/forecast?commodity=${encodeURIComponent(params.commodity)}&city=${encodeURIComponent(params.city)}`,
+    ),
+  anomalies: (params: {
+    commodity?: string;
+    city?: string;
+    limit?: number;
+    since?: string;
+  }) => {
+    const q = new URLSearchParams();
+    if (params.commodity) q.set("commodity", params.commodity);
+    if (params.city) q.set("city", params.city);
+    if (params.limit) q.set("limit", String(params.limit));
+    if (params.since) q.set("since", params.since);
+    return fetchJson<AnomaliesResponse>(`/api/v1/anomalies?${q.toString()}`);
+  },
+  // Plan + remaining free-tier quota for a WhatsApp number. The API hashes the
+  // number server-side; it is never stored in raw form.
+  billingStatus: (phone: string) =>
+    fetchJson<BillingStatus>(
+      `/billing/status?phone=${encodeURIComponent(phone)}`,
+    ),
+};

dashboard/app/lib/auth.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+// Auth context for the dashboard.
+//
+// Wraps Supabase Auth in a shape the UI can consume without knowing whether
+// Supabase is configured at all. When it is not (the offline demo), `configured`
+// is false, `user` stays null, and the sign-in calls return a clear error rather
+// than throwing — the public map keeps working either way.
+
+import {
+  createContext, useCallback, useContext, useEffect, useMemo, useState,
+} from "react";
+import type { Session, User } from "@supabase/supabase-js";
+import { getSupabase, isAuthConfigured } from "./supabase";
+import {
+  credentialsMatch, currentDevUser, enterDev, exitDev, DEV_LOGIN_ENABLED,
+} from "./devauth";
+import { exitGuest } from "./guest";
+
+// Minimal object shaped enough for the UI (AccountMenu and /account read only
+// `email`). Used to represent a dev-login session, which has no real Supabase
+// User behind it. Never sent to the backend.
+function makeDevUser(email: string): User {
+  return { id: "dev-admin", email, aud: "dev", app_metadata: {}, user_metadata: {},
+           created_at: "" } as unknown as User;
+}
+
+type AuthResult = { error: string | null };
+
+type AuthContextValue = {
+  user: User | null;
+  session: Session | null;
+  loading: boolean;
+  configured: boolean;
+  signIn: (email: string, password: string) => Promise<AuthResult>;
+  signUp: (email: string, password: string) => Promise<AuthResult>;
+  signOut: () => Promise<void>;
+  requestPasswordReset: (email: string) => Promise<AuthResult>;
+  updatePassword: (newPassword: string) => Promise<AuthResult>;
+};
+
+const NOT_CONFIGURED =
+  "Login belum aktif di lingkungan ini. Atur NEXT_PUBLIC_SUPABASE_URL dan NEXT_PUBLIC_SUPABASE_ANON_KEY.";
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+export function AuthProvider({ children }: { children: React.ReactNode }) {
+  const configured = isAuthConfigured();
+  const [session, setSession] = useState<Session | null>(null);
+  const [devUser, setDevUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(configured);
+
+  // Restore a dev-login session from its cookie on mount. Client-only, and a
+  // no-op unless NEXT_PUBLIC_DEV_LOGIN is on, so production carries no trace.
+  useEffect(() => {
+    const email = currentDevUser();
+    if (email) setDevUser(makeDevUser(email));
+  }, []);
+
+  useEffect(() => {
+    const supabase = getSupabase();
+    if (!supabase) {
+      setLoading(false);
+      return;
+    }
+    let active = true;
+
+    supabase.auth.getSession().then(({ data }) => {
+      if (!active) return;
+      setSession(data.session);
+      setLoading(false);
+    });
+
+    // Keeps this tab in sync with sign-in/out that happened elsewhere,
+    // including token refreshes.
+    const { data: sub } = supabase.auth.onAuthStateChange((_event, next) => {
+      setSession(next);
+    });
+
+    return () => {
+      active = false;
+      sub.subscription.unsubscribe();
+    };
+  }, []);
+
+  const signIn = useCallback(async (email: string, password: string) => {
+    // Dev-login short-circuit, checked before Supabase. credentialsMatch is
+    // hard-false unless NEXT_PUBLIC_DEV_LOGIN is on, so this branch does not
+    // exist in a production build.
+    if (credentialsMatch(email, password)) {
+      enterDev(email);
+      setDevUser(makeDevUser(email));
+      return { error: null };
+    }
+    const supabase = getSupabase();
+    if (!supabase) return { error: NOT_CONFIGURED };
+    const { error } = await supabase.auth.signInWithPassword({ email, password });
+    return { error: error?.message ?? null };
+  }, []);
+
+  const signUp = useCallback(async (email: string, password: string) => {
+    const supabase = getSupabase();
+    if (!supabase) return { error: NOT_CONFIGURED };
+    const { error } = await supabase.auth.signUp({ email, password });
+    return { error: error?.message ?? null };
+  }, []);
+
+  const signOut = useCallback(async () => {
+    await getSupabase()?.auth.signOut();
+    // Clear every way a visitor could be "in" so sign-out is complete.
+    exitDev();
+    exitGuest();
+    setDevUser(null);
+    setSession(null);
+  }, []);
+
+  // Step 1 of password recovery: ask Supabase to email a link. The link
+  // lands the visitor back on /reset-password?code=... . redirectTo must be
+  // present in the Supabase project's Authentication > URL Configuration
+  // allow-list, or Supabase silently falls back to the Site URL instead —
+  // see docs/DEPLOY_AUTH.md.
+  const requestPasswordReset = useCallback(async (email: string) => {
+    const supabase = getSupabase();
+    if (!supabase) return { error: NOT_CONFIGURED };
+    const { error } = await supabase.auth.resetPasswordForEmail(email, {
+      redirectTo: `${window.location.origin}/reset-password`,
+    });
+    return { error: error?.message ?? null };
+  }, []);
+
+  // Step 2: called from /reset-password once the recovery link has been
+  // exchanged for a session (see app/lib/supabase.ts — the browser client's
+  // detectSessionInUrl does that exchange automatically on load). updateUser
+  // works against whatever session is currently active, recovery or normal.
+  const updatePassword = useCallback(async (newPassword: string) => {
+    const supabase = getSupabase();
+    if (!supabase) return { error: NOT_CONFIGURED };
+    const { error } = await supabase.auth.updateUser({ password: newPassword });
+    return { error: error?.message ?? null };
+  }, []);
+
+  const value = useMemo<AuthContextValue>(
+    () => ({
+      // A real Supabase session wins; the dev user is the fallback identity.
+      user: session?.user ?? devUser,
+      session,
+      loading,
+      configured: configured || DEV_LOGIN_ENABLED,
+      signIn,
+      signUp,
+      signOut,
+      requestPasswordReset,
+      updatePassword,
+    }),
+    [session, devUser, loading, configured, signIn, signUp, signOut,
+     requestPasswordReset, updatePassword],
+  );
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+export function useAuth(): AuthContextValue {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error("useAuth must be used inside <AuthProvider>");
+  return ctx;
+}

dashboard/app/lib/devauth.ts

@@ -0,0 +1,50 @@
+// Development-only login (email/password = admin/admin by default).
+//
+// ⚠ THIS IS A DEV CONVENIENCE, NOT REAL AUTH. It exists so the signed-in
+// experience can be tested before a Supabase project is wired up. It accepts a
+// hardcoded credential and issues a client-side cookie — it does NOT verify
+// anything against a server.
+//
+// PRODUCTION SAFETY
+// -----------------
+// The whole path is gated on NEXT_PUBLIC_DEV_LOGIN === "true", which is set
+// ONLY in the gitignored .env.local. It is deliberately absent from
+// .env.example and must never be set in the Vercel production environment.
+// NEXT_PUBLIC_* values are inlined at build time, so a production build made
+// without the flag has this code permanently disabled — DEV_LOGIN_ENABLED is a
+// compile-time false and the dead branch cannot be reached.
+//
+// Even if someone did enable it in production, the blast radius is small: the
+// dev cookie only gets a visitor past the page-routing funnel to the map, which
+// serves public government data. It does NOT authenticate against the backend
+// API — token-gated endpoints (subscriber/billing) verify a real Supabase JWT,
+// which this cookie is not. So a leaked dev login cannot read anyone's data.
+
+export const DEV_LOGIN_ENABLED = process.env.NEXT_PUBLIC_DEV_LOGIN === "true";
+export const DEV_EMAIL = process.env.NEXT_PUBLIC_DEV_EMAIL ?? "admin";
+export const DEV_PASSWORD = process.env.NEXT_PUBLIC_DEV_PASSWORD ?? "admin";
+
+export const DEV_COOKIE = "agriflow_dev"; // keep in sync with proxy.ts
+
+const DEV_MAX_AGE = 12 * 60 * 60; // 12h, matches the guest session
+
+export function credentialsMatch(email: string, password: string): boolean {
+  return DEV_LOGIN_ENABLED && email === DEV_EMAIL && password === DEV_PASSWORD;
+}
+
+export function enterDev(email: string): void {
+  document.cookie =
+    `${DEV_COOKIE}=${encodeURIComponent(email)}; path=/; max-age=${DEV_MAX_AGE}; SameSite=Lax`;
+}
+
+export function exitDev(): void {
+  document.cookie = `${DEV_COOKIE}=; path=/; max-age=0; SameSite=Lax`;
+}
+
+export function currentDevUser(): string | null {
+  if (typeof document === "undefined" || !DEV_LOGIN_ENABLED) return null;
+  const hit = document.cookie
+    .split("; ")
+    .find((c) => c.startsWith(`${DEV_COOKIE}=`));
+  return hit ? decodeURIComponent(hit.slice(DEV_COOKIE.length + 1)) : null;
+}

dashboard/app/lib/guest.ts

@@ -0,0 +1,34 @@
+// Guest ("judge") access.
+//
+// The site is login-first: proxy.ts funnels every page to /login until you are
+// signed in. A guest cookie is the deliberate bypass so hackathon judges can
+// enter the dashboard without creating an account.
+//
+// THIS IS A UX FUNNEL, NOT A SECURITY BOUNDARY. The cookie is set client-side,
+// is not httpOnly, and anyone could set it by hand. That is acceptable because
+// the map runs on public government reference data, and the things that
+// actually need protecting (subscriber/billing data) are guarded server-side
+// by JWT verification in the FastAPI layer, not by this cookie. Do not gate
+// anything sensitive on guest state.
+
+export const GUEST_COOKIE = "agriflow_guest";
+
+// 12 hours: long enough for a judging session, short enough that a shared
+// machine does not stay "logged in as guest" indefinitely.
+const GUEST_MAX_AGE = 12 * 60 * 60;
+
+export function enterGuest(): void {
+  document.cookie =
+    `${GUEST_COOKIE}=1; path=/; max-age=${GUEST_MAX_AGE}; SameSite=Lax`;
+}
+
+export function exitGuest(): void {
+  document.cookie = `${GUEST_COOKIE}=; path=/; max-age=0; SameSite=Lax`;
+}
+
+export function isGuest(): boolean {
+  if (typeof document === "undefined") return false;
+  return document.cookie
+    .split("; ")
+    .some((c) => c === `${GUEST_COOKIE}=1`);
+}

dashboard/app/lib/supabase.ts

@@ -0,0 +1,37 @@
+// Supabase browser client for dashboard auth.
+//
+// Auth is OPTIONAL by design. The public map is the hackathon demo surface and
+// must render on a fresh clone with no Supabase project attached, so this
+// module returns null when the environment is not configured and every caller
+// treats that as "auth unavailable" rather than throwing. Check isAuthConfigured()
+// before offering a sign-in affordance.
+//
+// WHY @supabase/ssr AND NOT createClient
+// --------------------------------------
+// createClient() from supabase-js keeps the session in localStorage, which the
+// server cannot read — proxy.ts would have no way to see whether a visitor is
+// signed in. createBrowserClient() from @supabase/ssr stores the session in
+// cookies instead, so the same session is visible to both the browser and the
+// server. That is what makes server-side route protection possible at all.
+
+import { createBrowserClient } from "@supabase/ssr";
+import type { SupabaseClient } from "@supabase/supabase-js";
+
+const URL = process.env.NEXT_PUBLIC_SUPABASE_URL;
+const ANON_KEY = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+
+export function isAuthConfigured(): boolean {
+  return Boolean(URL && ANON_KEY);
+}
+
+let client: SupabaseClient | null = null;
+
+export function getSupabase(): SupabaseClient | null {
+  if (!isAuthConfigured()) return null;
+  // Created lazily and memoized: instantiating per render would drop the
+  // in-memory session and log the user out on every navigation.
+  if (!client) {
+    client = createBrowserClient(URL!, ANON_KEY!);
+  }
+  return client;
+}

dashboard/app/login/LoginForm.tsx

@@ -0,0 +1,214 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import Link from "next/link";
+import { useRouter, useSearchParams } from "next/navigation";
+import { useAuth } from "../lib/auth";
+import { enterGuest } from "../lib/guest";
+import { DEV_LOGIN_ENABLED, DEV_EMAIL, DEV_PASSWORD } from "../lib/devauth";
+
+type Mode = "signin" | "signup";
+
+export default function LoginForm() {
+  const { signIn, signUp, configured, user } = useAuth();
+  const router = useRouter();
+  const searchParams = useSearchParams();
+
+  // proxy.ts appends ?next= when it funnels someone off a gated page.
+  // Only relative paths are honoured — accepting an absolute URL here would
+  // make this an open redirect an attacker could point at their own site.
+  // Default to the map (/), which is the app's home, not /account.
+  const rawNext = searchParams.get("next");
+  const nextPath =
+    rawNext && rawNext.startsWith("/") && !rawNext.startsWith("//")
+      ? rawNext
+      : "/";
+
+  const [mode, setMode] = useState<Mode>("signin");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  // Send an already-signed-in visitor away from the login page. This runs in an
+  // effect, not in render: calling router.replace() during render triggers
+  // React's "Cannot update a component (Router) while rendering a different
+  // component (LoginForm)" warning (a hard error under stricter React modes).
+  useEffect(() => {
+    if (user) router.replace(nextPath);
+  }, [user, nextPath, router]);
+
+  if (user) {
+    // Redirect is in flight (handled by the effect above); render nothing.
+    return null;
+  }
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    setNotice(null);
+    setBusy(true);
+    const fn = mode === "signin" ? signIn : signUp;
+    const { error } = await fn(email, password);
+    setBusy(false);
+
+    if (error) {
+      setError(error);
+      return;
+    }
+    if (mode === "signup") {
+      // Supabase may require email confirmation depending on project settings,
+      // so we cannot assume a session exists yet.
+      setNotice(
+        "Akun dibuat. Jika diminta, cek email Anda untuk tautan konfirmasi, lalu masuk.",
+      );
+      setMode("signin");
+      return;
+    }
+    // Full navigation (not router.push) so the proxy re-runs and sees the
+    // freshly-set session/dev cookie, letting the destination through.
+    window.location.assign(nextPath);
+  }
+
+  function enterAsGuest() {
+    enterGuest();
+    // Full navigation (not router.push) so the proxy re-runs and now sees the
+    // guest cookie, letting the destination page through.
+    window.location.assign(nextPath);
+  }
+
+  return (
+    <main className="flex-1 flex items-center justify-center p-6 bg-slate-50">
+      <div className="w-full max-w-sm">
+        <h1 className="text-2xl font-semibold text-slate-900">
+          {mode === "signin" ? "Masuk ke AgriFlow" : "Buat akun AgriFlow"}
+        </h1>
+        <p className="mt-1 text-sm text-slate-500">
+          Untuk pelanggan dinas, TPID, dan mitra data.
+        </p>
+
+        {DEV_LOGIN_ENABLED && (
+          <p className="mt-4 rounded-lg bg-sky-50 border border-sky-200 p-3 text-sm text-sky-900">
+            Mode pengembangan aktif. Login uji: <b>{DEV_EMAIL}</b> / <b>{DEV_PASSWORD}</b>.
+          </p>
+        )}
+
+        {!configured && (
+          <p className="mt-4 rounded-lg bg-sky-50 border border-sky-200 p-3 text-sm text-sky-900">
+            Login akun untuk dinas, TPID, dan mitra data akan segera hadir. Untuk
+            meninjau peta dan rekomendasi sekarang, silakan pilih <b>Masuk sebagai
+            Tamu</b> di bawah.
+          </p>
+        )}
+
+        <form onSubmit={onSubmit} className="mt-6 space-y-4">
+          <div>
+            <label htmlFor="email" className="block text-sm font-medium text-slate-700">
+              Email
+            </label>
+            <input
+              id="email"
+              // Dev login uses a non-email username ("admin"), which type=email
+              // would reject before submit. Relax to text only when dev login
+              // is on; production keeps real email validation.
+              type={DEV_LOGIN_ENABLED ? "text" : "email"}
+              required
+              autoComplete="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              className="mt-1 w-full rounded-lg border border-slate-300 px-3 py-2 text-sm
+                         focus:border-emerald-600 focus:outline-none focus:ring-1 focus:ring-emerald-600"
+            />
+          </div>
+
+          <div>
+            <div className="flex items-center justify-between">
+              <label htmlFor="password" className="block text-sm font-medium text-slate-700">
+                Kata sandi
+              </label>
+              {mode === "signin" && (
+                <Link
+                  href={`/forgot-password${email ? `?email=${encodeURIComponent(email)}` : ""}`}
+                  className="text-sm text-emerald-700 hover:underline"
+                >
+                  Lupa kata sandi?
+                </Link>
+              )}
+            </div>
+            <input
+              id="password"
+              type="password"
+              required
+              // Enforce length only when CREATING a password (signup). On
+              // signin you are entering an existing one, so a length rule here
+              // is wrong, and it was also blocking the short dev-login password.
+              minLength={mode === "signup" ? 8 : undefined}
+              autoComplete={mode === "signin" ? "current-password" : "new-password"}
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              className="mt-1 w-full rounded-lg border border-slate-300 px-3 py-2 text-sm
+                         focus:border-emerald-600 focus:outline-none focus:ring-1 focus:ring-emerald-600"
+            />
+            {mode === "signup" && (
+              <p className="mt-1 text-xs text-slate-500">Minimal 8 karakter.</p>
+            )}
+          </div>
+
+          {error && (
+            <p role="alert" className="rounded-lg bg-red-50 border border-red-200 p-3 text-sm text-red-800">
+              {error}
+            </p>
+          )}
+          {notice && (
+            <p className="rounded-lg bg-emerald-50 border border-emerald-200 p-3 text-sm text-emerald-900">
+              {notice}
+            </p>
+          )}
+
+          <button
+            type="submit"
+            disabled={busy || !configured}
+            className="w-full rounded-lg bg-emerald-700 px-4 py-2.5 text-sm font-medium text-white
+                       hover:bg-emerald-800 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            {busy ? "Memproses…" : mode === "signin" ? "Masuk" : "Daftar"}
+          </button>
+        </form>
+
+        <div className="mt-6 flex items-center gap-3">
+          <span className="h-px flex-1 bg-slate-200" />
+          <span className="text-xs text-slate-400">atau</span>
+          <span className="h-px flex-1 bg-slate-200" />
+        </div>
+
+        <button
+          type="button"
+          onClick={enterAsGuest}
+          className="mt-6 w-full rounded-lg border border-slate-300 px-4 py-2.5 text-sm
+                     font-medium text-slate-700 hover:bg-slate-50"
+        >
+          Masuk sebagai Tamu (juri)
+        </button>
+        <p className="mt-2 text-center text-xs text-slate-400">
+          Akses peta &amp; data untuk peninjauan, tanpa membuat akun.
+        </p>
+
+        <p className="mt-6 text-center text-sm text-slate-600">
+          {mode === "signin" ? "Belum punya akun? " : "Sudah punya akun? "}
+          <button
+            type="button"
+            onClick={() => {
+              setMode(mode === "signin" ? "signup" : "signin");
+              setError(null);
+              setNotice(null);
+            }}
+            className="font-medium text-emerald-700 hover:underline"
+          >
+            {mode === "signin" ? "Daftar" : "Masuk"}
+          </button>
+        </p>
+      </div>
+    </main>
+  );
+}

dashboard/app/login/page.tsx

@@ -0,0 +1,19 @@
+import { Suspense } from "react";
+import LoginForm from "./LoginForm";
+
+// useSearchParams() forces client-side rendering for whatever subtree reads it,
+// so the form lives behind a Suspense boundary. Without this the /login route
+// cannot be prerendered and the build fails.
+export default function LoginPage() {
+  return (
+    <Suspense
+      fallback={
+        <main className="flex-1 grid place-items-center text-slate-500">
+          Memuat…
+        </main>
+      }
+    >
+      <LoginForm />
+    </Suspense>
+  );
+}