GPU-Gateway Integration Program — ahu-ocr-tidyup (2026-07-06)

For agentic workers: coordinator-driven SDD; one wave = one implementer + review loop. Source prompt: https://x056.think.val.id/prompt-ahu-ocr-tidyup.md · Canonical contract: ahu-gpu-manager/docs/CONVENTIONS.md v1.0 (WINS on any conflict).

Goal: every model/OCR egress in this engine goes through shared clients that carry the CONVENTIONS §2 header set, with gateway routing DORMANT until env flip (unset env = byte-identical behavior).

Hard constraints (verbatim from prompt):
- Backwards-compatible and DORMANT. No live .env values flipped — only commented future entries.
- Phase A (chat egress via MODEL_GATEWAY_URL + /v1) flips first; Phase B (job API + Azure DI + PaddleOCR + classifier seams) prepared now, flips later — keep current default URLs.
- Tenant slug X-Tenant-Id: ahu-ocr (stable forever). X-Surface: internal. X-Priority: batch for pipeline stages, interactive for verifier-triggered actions. Idempotency-Key deterministic (documentId + pipelineStage + contentHash), REQUIRED on job submits. X-Request-Id generated once at outermost entry, propagated (audit trace_id). X-Doc-Hash/X-Doc-Pages additive on document calls.
- Clock rule §3.3: processing-timeout clock runs ONLY during processing; queued bounded by new GPU_QUEUE_WAIT_MS (default 1800000). 404 JOB_UNKNOWN → resubmit with SAME idempotency key. Pass through queue_position/eta_ms.
- 429/503 + Retry-After = graceful degradation (honor Retry-After on any retry; no retry storms).
- Model ids via gateway = registry aliases (qwen-35b, cleanup-3b, …) — new *_MODEL envs defaulting to today's raw names.
- src/scripts/ CLI harnesses excluded (dev tools, not runtime egress).
- GATEWAY_URL for commented env entries: http://192.168.83.20:8200.

Surveyed egress inventory (2026-07-06, tidy HEAD 4e1d2a1):
- Job submit-poll (Phase B): ocr/gpu-server.ts, ocr/azure-on-prem-domisili.ts, ocr/azure-on-prem-bukti-setor.ts, llm/ktp-cleanup.ts, llm/override-scrutiny.ts, llm/pendirian-pp-extract.ts, llm/perbaikan-advisory.ts, llm/surat-pernyataan-extract.ts, services/document-processor.ts, services/perbaikan-ai-summary-worker.ts
- Chat completions (Phase A): llm/small-card-cleanup.ts, ocr/paddleocr-bukti-setor-extract.ts, ocr/paddleocr-contact-info-extract.ts, ocr/paddleocr-domisili-extract.ts, ocr/paddleocr-sp-pendirian-pp-extract.ts, services/akta-koran-extract.ts, services/akta-peleburan-sources-extract.ts, services/akta-txn-classifier.ts, services/apostille-classifier.ts, services/apostille-generic-extract.ts, services/bukti-pengumuman-extract.ts, services/laporan-keuangan-extract.ts, services/surat-likuidator-extract.ts
- Azure DI direct (Phase B seam): ocr/azure-on-prem-{layout,ktp,npwp,id-document,contact-info,sp-pendirian-pp,bukti-setor-custom}.ts (+ azure paths in document-processor)
- PaddleOCR (Phase B seam): ocr/paddleocr-layout.ts, ocr/ocr-ensemble.ts
- Classifier (Phase B seam): ocr/classifier.ts (+ CLASSIFIER_URL reads in routes/klasifikasi.ts, services/akta-txn-classifier.ts, services/akta-peleburan-sources-extract.ts)

Waves

• [ ] W1 — Foundations: backend/src/lib/gateway-headers.ts (context→header assembly; X-Request-Id threaded via existing request context; deterministic idempotency-key builder; doc-hash reuse) + env prep §6 (commented entries in .env.example/.env) + unit tests (header assembly, trace propagation, key determinism).
• [ ] W2 — Chat client (Phase A): backend/src/lib/gateway-chat-client.ts — base URL = MODEL_GATEWAY_URL+"/v1" when set else caller's current URL; §1 headers; 429/503 Retry-After honor; *_MODEL alias envs defaulting to raw names. Migrate all 13 runtime chat callers preserving exact payload/timeout/error semantics. Dormancy proof per caller.
• [ ] W3 — Job client (Phase B): backend/src/lib/gpu-job-client.ts — submit/poll/timeout/error-mapping preserving each caller's exact endpoint+payload+timeouts; §3.3 clocks (GPU_QUEUE_WAIT_MS; processing-only clock); JOB_UNKNOWN→resubmit same key; queue_position/eta_ms passthrough; §1 headers on submit. Migrate the 10 job callers. Unit tests for clock/JOB_UNKNOWN behaviors.
• [ ] W4 — OCR/classifier seams + doc identity + program verification: base-URL seams for azure-*/paddleocr/classifier (headers now, URLs unchanged); X-Doc-Hash/X-Doc-Pages on document calls; full-gate run; dormancy proof (constructed URLs/bodies/headers-minus-additive unchanged); deploy to staging + one-document smoke; final report per prompt §7.

Gates every wave: backend ./node_modules/.bin/tsc --noEmit + TEST_DATABASE_URL=postgresql://ahu:ahu_dev@192.168.83.20:5434/ahu_ocr_sandbox_test bun run test (bun at ~/.bun/bin, reinstall via bun.sh if missing); frontend untouched (spot-run if any shared type moves). Zero regressions. TDD for all new logic.