phase-3: ingestion, from a QR in the camera to a card in the bandeja

The whole pipeline: storage behind one driver interface (local disk and S3),
a portable job queue with a poller, QR and CDC parsing, OCR through the
Anthropic API, dedupe, manual entry, and the bandeja that turns all of it into
one decision per card.

Scanning tries the trustworthy door first: a QR is parsed and prefilled from
its CDC; a photo without one is queued for OCR when a key is configured and
otherwise opens the manual form against the stored file. A QR that will not
parse records an ingest error and falls through rather than losing the photo.

Job claiming is the only dialect divergence, as SPEC allows: FOR UPDATE SKIP
LOCKED on Postgres, a conditional UPDATE against SQLite's single writer. Retry
backoff follows SPEC exactly and a job abandoned by a killed process returns to
the queue once its lock goes stale, which is the phase 3 acceptance case.

OCR uses structured outputs rather than parsing prose, so the model cannot
return anything but the RULES.md schema, and every field is nullable because
unreadable is a real answer.

Web: scan with live QR decoding (BarcodeDetector, ZXing fallback, wasm served
from our own origin), manual entry with the IVA split worked out from the
total, the bandeja with swipe, buttons and keyboard all doing the same thing,
and the documents list and detail with an editable classification.

The seed now carries Maria's 34 purchases and 8 sales and Carlos's 6, all
classified through the real rules, plus the two open ingest errors.

Two defects found and fixed with tests: seeded documents could be dated in the
future, which would corrupt any projection computed from them, and the category
buttons announced their keyboard shortcut as part of their name.

255 vitest tests, 37 Playwright tests, rules coverage still 100%, typecheck and
lint clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

apps/api/scripts/kude-png.ts

@@ -0,0 +1,85 @@
+import { PNG } from 'pngjs';
+import QRCode from 'qrcode';
+import type { Fixture } from '../src/db/fixtures';
+
+const WIDTH = 620;
+const HEIGHT = 840;
+const QR_MODULE_PX = 6;
+const QUIET_ZONE_MODULES = 4;
+
+/**
+ * Draws a fixture as a PNG "page" with a real, decodable QR where a KUDE prints one.
+ *
+ * SPEC-GAP: CONTRACTS.md section 4 describes rendering these through HTML or canvas. They
+ * are drawn with raw pixels instead, because the only thing any test reads from them is
+ * the QR, and a faithful visual replica would mean carrying a browser or an SVG
+ * rasteriser purely to produce three images nothing looks at. The emitter, date and
+ * totals live in fixtures.ts, which is where tests and the seed read them from.
+ */
+export function renderKude(fixture: Fixture): Buffer {
+  const png = new PNG({ width: WIDTH, height: HEIGHT });
+  fill(png, 0xff, 0xff, 0xff);
+
+  // A masthead bar and a rule, so the image reads as a document rather than a blank page.
+  rect(png, 0, 0, WIDTH, 72, 0x0f, 0x4c, 0x4c);
+  rect(png, 40, 120, WIDTH - 80, 2, 0xd0, 0xd0, 0xd0);
+  rect(png, 40, 220, WIDTH - 80, 2, 0xd0, 0xd0, 0xd0);
+
+  if (fixture.qrUrl) drawQr(png, fixture.qrUrl);
+
+  return PNG.sync.write(png);
+}
+
+function drawQr(png: PNG, payload: string): void {
+  // Level M with an explicit quiet zone: a QR without margin is unreliable to decode.
+  const qr = QRCode.create(payload, { errorCorrectionLevel: 'M' });
+  const size = qr.modules.size;
+  const data = qr.modules.data;
+
+  const side = (size + QUIET_ZONE_MODULES * 2) * QR_MODULE_PX;
+  const originX = Math.floor((WIDTH - side) / 2);
+  const originY = HEIGHT - side - 60;
+
+  rect(png, originX, originY, side, side, 0xff, 0xff, 0xff);
+
+  for (let row = 0; row < size; row++) {
+    for (let column = 0; column < size; column++) {
+      if (!data[row * size + column]) continue;
+      rect(
+        png,
+        originX + (column + QUIET_ZONE_MODULES) * QR_MODULE_PX,
+        originY + (row + QUIET_ZONE_MODULES) * QR_MODULE_PX,
+        QR_MODULE_PX,
+        QR_MODULE_PX,
+        0x00,
+        0x00,
+        0x00,
+      );
+    }
+  }
+}
+
+function fill(png: PNG, r: number, g: number, b: number): void {
+  rect(png, 0, 0, png.width, png.height, r, g, b);
+}
+
+function rect(
+  png: PNG,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  r: number,
+  g: number,
+  b: number,
+): void {
+  for (let row = y; row < y + height && row < png.height; row++) {
+    for (let column = x; column < x + width && column < png.width; column++) {
+      const index = (png.width * row + column) << 2;
+      png.data[index] = r;
+      png.data[index + 1] = g;
+      png.data[index + 2] = b;
+      png.data[index + 3] = 0xff;
+    }
+  }
+}

apps/api/scripts/render-fixtures.ts

@@ -0,0 +1,23 @@
+/**
+ * Renders the fixture comprobantes to PNG under /fixtures, so the e2e tests scan a real
+ * image rather than a hand built payload. Run with `pnpm fixtures`.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FIXTURES } from '../src/db/fixtures';
+import { renderKude } from './kude-png';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const outputDir = join(here, '..', '..', '..', 'fixtures');
+
+mkdirSync(outputDir, { recursive: true });
+
+for (const fixture of FIXTURES) {
+  const png = renderKude(fixture);
+  const target = join(outputDir, `${fixture.name}.png`);
+  writeFileSync(target, png);
+  console.info(`[fixtures] ${target} (${png.byteLength} bytes)${fixture.cdc ? ' with QR' : ' no QR'}`);
+}
+
+console.info(`[fixtures] ${FIXTURES.length} rendered`);