chore(release): v1.0.25

Cut by rmancinas via the "Cut release" workflow. Pushing the tag triggers build.yml; deploy separately with tag=1.0.25.

.gitea/workflows/build.yml

@@ -14,7 +14,16 @@
 # ARG/ENV (APP_VERSION / GIT_SHA / BUILD_DATE) and as OCI labels, so a running
 # container can report exactly what is deployed.
 #
-# Release flow:  git tag v1.2.0 && git push origin v1.2.0  -> versioned images.
+# Release flow:  git tag v1.2.0 && git push origin v1.2.0  -> versioned images
+#                -> deploy-on-tag.yml waits for this run to go green and then
+#                   dispatches deploy-galactus.yml.
+#
+# This workflow BUILDS ONLY — it never deploys. The deploy chain used to be a
+# job here, gated to tag refs, but Gitea draws every job of a workflow into the
+# run graph before it evaluates the job's `if`: a routine master build showed a
+# pending "Deploy to galactus" and looked like prod was about to be redeployed
+# off an unreleased commit. Keeping the deploy in a `on: push: tags` workflow of
+# its own makes that structurally impossible.
 
 name: Build and Push Images
 

.gitea/workflows/deploy-galactus.yml

@@ -17,6 +17,12 @@
 #   3. prisma migrate deploy  forward-only. Prisma has no down-migrations; see
 #                           docs/DEPLOY_AND_MIGRATIONS.md — expand/contract is
 #                           the rule, the backup is the emergency lever.
+#                           Done HERE so the schema moves while the OLD code is
+#                           still serving. The api container ALSO migrates at
+#                           start (docker/api-entrypoint.sh); `migrate deploy`
+#                           is idempotent, so the second run is a no-op and the
+#                           container is what covers a restart that never goes
+#                           through this workflow at all.
 #   4. app (api + web)      the new images.
 #   5. verify               ask the running API what it actually is.
 #
@@ -55,10 +61,10 @@
 #                                     uses until somebody saves them there
 #    These are NOT galactus-specific (no _GALACTUS suffix) — one SES identity
 #    serves every deployment.
-#  - The runner (which lives on cubex) must be able to reach BOTH
+#  - The runner (which lives on cubex) must be able to reach galactus:9443
-#    galactus:9443 (Portainer) and galactus:3306 (MySQL, for migrate deploy).
+#    (Portainer). It should also reach galactus:3306 for step 3, but that is
-#    If it cannot reach 3306, run the migration by hand from a host that can
+#    no longer load-bearing: dispatch with skip_migrate=true and the api
-#    and dispatch with skip_migrate=true.
+#    container applies the migrations itself at start.
 #  - ONE-TIME, on a database that predates migration history (i.e. one built
 #    with `prisma db push`): baseline it before the first run, or step 3 fails
 #    with P3005 "database schema is not empty":
@@ -88,7 +94,7 @@ on:
         required: false
         default: false
       skip_migrate:
-        description: "Skip prisma migrate deploy (use when the runner cannot reach MySQL and you migrated by hand)"
+        description: "Skip the runner-side migrate step (safe: the api container migrates at start)"
         type: boolean
         required: false
         default: false
@@ -237,6 +243,10 @@ jobs:
         run: node deploy/scripts/pre-migrate-backup.mjs
 
       # --- schema, forward-only ---------------------------------------------
+      # Belt to the container's braces: this runs while the OLD code is still
+      # serving, which is the order expand/contract is designed around. The
+      # api container repeats it at start for the paths this step cannot
+      # reach (skip_migrate, a host reboot, a stack re-applied by hand).
       - name: Apply database migrations
         if: ${{ github.event.inputs.skip_migrate != 'true' }}
         env:
@@ -281,13 +291,20 @@ jobs:
           standalone: true
           pull: true
           endpoint: ${{ secrets.PORTAINER_ENDPOINT_ID_GALACTUS }}
+          # NOTE: the block below is parsed as JSON — no comments inside it.
+          #
+          # API_ORIGIN is deliberately absent. The browser derives the API origin
+          # from the page it loaded (apps/web/src/lib/api.ts), so the deployment
+          # survives the box moving between the tailnet, the office LAN and a
+          # demo domain. Setting it here would pin it again and re-break an https
+          # front door with mixed active content. APP_API_ORIGIN_GALACTUS lives
+          # on only as the URL the verify step probes.
           env_data: |
             {
               "APP_TAG": "${{ github.event.inputs.tag }}",
               "API_PORT": "3001",
               "WEB_PORT": "3000",
               "S3_BUCKET": "jorgecuadros-documents",
-              "API_ORIGIN": "${{ secrets.APP_API_ORIGIN_GALACTUS }}",
               "WEB_ORIGIN": "${{ secrets.APP_WEB_ORIGIN_GALACTUS }}",
               "S3_ENDPOINT": "${{ secrets.APP_S3_ENDPOINT_GALACTUS }}",
               "DATABASE_URL": "${{ secrets.DATABASE_URL_GALACTUS }}",
@@ -295,6 +312,9 @@ jobs:
               "SESSION_COOKIE_SECURE": "false",
               "OPS_DB_ADMIN_USER": "root",
               "OPS_DB_ADMIN_PASSWORD": "${{ secrets.MYSQL_ROOT_PASSWORD }}",
+              "REPLICA_DB_HOST": "${{ secrets.REPLICA_DB_HOST }}",
+              "REPLICA_DB_USER": "${{ secrets.REPLICA_DB_USER }}",
+              "REPLICA_DB_PASS": "${{ secrets.REPLICA_DB_PASS }}",
               "MINIO_ROOT_USER": "${{ secrets.MINIO_ROOT_USER }}",
               "MINIO_ROOT_PASSWORD": "${{ secrets.MINIO_ROOT_PASSWORD }}",
               "SES_REGION": "${{ secrets.SES_REGION }}",
@@ -319,6 +339,12 @@ jobs:
         run: |
           set -e
           apk add --no-cache curl >/dev/null
+          # These secrets are CORS origin LISTS as far as the app is concerned
+          # (WEB_ORIGIN is comma-separated so one deployment can be reached by
+          # LAN IP, tailnet name and demo domain at once). A list is not a URL,
+          # so probe the FIRST entry — keep the runner-reachable origin first.
+          API_ORIGIN=${API_ORIGIN%%,*}
+          WEB_ORIGIN=${WEB_ORIGIN%%,*}
           fetch_version() {
             for i in $(seq 1 30); do
               if curl -fsS "$1/version" > "$2"; then return 0; fi

.gitea/workflows/deploy-on-tag.yml

@@ -0,0 +1,199 @@
+# Chain the PROD deploy onto a green tag build.
+#
+# This is a SEPARATE workflow, not a job in build.yml, and the trigger is the
+# whole point: `on: push: tags` cannot fire on a push to master. When this was a
+# `deploy` job inside build.yml gated by `if: startsWith(github.ref,
+# 'refs/tags/v')`, Gitea still drew "Deploy to galactus" into the job graph of
+# every ordinary master build — the `if` is not evaluated until `needs` resolve,
+# so the job sits there looking like an imminent production deploy on a commit
+# nobody released. That is indistinguishable from a real misfire, and the only
+# safe reaction is to cancel the run, which kills the images with it.
+#
+# What it does NOT do is build. build.yml already builds and pushes both images
+# from one run; this waits for that run to go green and then dispatches
+# deploy-galactus.yml, which only pulls.
+#
+# Why wait for the build run rather than just dispatching: deploy-galactus.yml
+# pulls api and web at the same tag, and a half-pushed pair is exactly the state
+# that leaves prod running one new image and one old one. The build run turning
+# green is the signal that both are in the registry.
+#
+# Why a dispatch and not a `workflow_run:` trigger, which Gitea does support as
+# of 1.24: deploy-galactus.yml reads `github.event.inputs.*` in ten places (tag,
+# scope, bootstrap, skip_migrate). Under workflow_run every one of them is the
+# empty string, so the deploy would silently run with no tag and scope != 'full'.
+# A dispatch keeps that workflow's contract intact and keeps it hand-runnable for
+# rollbacks, which is the whole point of it.
+#
+# Kill switch: set the repo variable AUTO_DEPLOY_GALACTUS to `false` to cut the
+# chain and go back to dispatching the deploy by hand. Anything else (including
+# unset) deploys.
+
+name: Deploy on tag
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  deploy:
+    name: Deploy to galactus
+    runs-on: docker
+    container:
+      image: node:20-alpine
+    steps:
+      - name: Preflight — RELEASE_TOKEN
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          set -eu
+          if [ -z "${RELEASE_TOKEN:-}" ]; then
+            echo "::error::Secret RELEASE_TOKEN is not set, so this cannot wait"
+            echo "::error::for the build or dispatch the deploy. Once build.yml"
+            V=${GITHUB_REF#refs/tags/}
+            echo "::error::is green, run 'Deploy to galactus' by hand with tag=${V#v}."
+            exit 1
+          fi
+
+      - name: Wait for the tag build, then dispatch deploy-galactus.yml
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          AUTO_DEPLOY: ${{ vars.AUTO_DEPLOY_GALACTUS }}
+          TAG_REF: ${{ github.ref }}
+          BUILD_SHA: ${{ github.sha }}
+        run: |
+          node -e '
+            const base = `${process.env.GITHUB_SERVER_URL}/api/v1/repos/${process.env.GITHUB_REPOSITORY}`;
+            const headers = { Authorization: `token ${process.env.RELEASE_TOKEN}` };
+            // refs/tags/v1.2.3 — derived from github.ref rather than ref_name so
+            // it does not depend on how Gitea populates GITHUB_REF_NAME.
+            const tagRef = process.env.TAG_REF;
+            const tag = tagRef.replace(/^refs\/tags\//, "");
+            // The git tag carries the leading v; the image tag does not.
+            const version = tag.replace(/^v/, "");
+            const sha = process.env.BUILD_SHA;
+            const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+            const runs = async () => {
+              const r = await fetch(`${base}/actions/runs?limit=50`, { headers });
+              if (!r.ok) throw new Error(`runs query failed: HTTP ${r.status}`);
+              return (await r.json()).workflow_runs || [];
+            };
+
+            // The release commit and its tag are the SAME sha, and build.yml
+            // skips the master run by design — so a sha match alone can latch
+            // onto that skipped run and call the build green when no image was
+            // ever pushed. Require the tag ref when the API reports one.
+            const isTagRun = (r) => {
+              const ref = r.head_branch || r.ref || "";
+              return !ref || ref === tag || ref === tagRef;
+            };
+
+            const buildRun = async () =>
+              (await runs()).find(
+                (r) =>
+                  r.head_sha === sha &&
+                  String(r.path || "").includes("build.yml") &&
+                  isTagRun(r),
+              );
+
+            // Gitea reports a run as `status` and mirrors it into `conclusion`;
+            // read whichever is populated rather than betting on one field.
+            const outcome = (r) => String(r.conclusion || r.status || "").toLowerCase();
+            const DONE = ["success", "failure", "cancelled", "canceled", "skipped"];
+
+            // Every deploy-galactus run id visible right now. A dispatch is only
+            // confirmed by an id that is NOT in here — a plain "is there a deploy
+            // run" check is satisfied by the PREVIOUS release run, and would
+            // report success for a dispatch that never took.
+            const deployRunIds = async () =>
+              new Set(
+                (await runs())
+                  .filter((r) => String(r.path || "").includes("deploy-galactus.yml"))
+                  .map((r) => r.id),
+              );
+
+            (async () => {
+              if (process.env.AUTO_DEPLOY === "false") {
+                console.log("AUTO_DEPLOY_GALACTUS=false — not deploying.");
+                console.log(`Deploy by hand with tag=${version} when ready.`);
+                return;
+              }
+
+              // ~20 min. A build is about 90s; the rest is queue time behind
+              // other runs on a single runner.
+              let run = null;
+              for (let i = 0; i < 80; i++) {
+                run = await buildRun();
+                if (run && DONE.includes(outcome(run))) break;
+                if (!run && i === 11) {
+                  // Two minutes with no run at all. The post-receive hook drops
+                  // runs silently when it errors (this cost v1.0.3 its images),
+                  // so say so rather than timing out with no explanation.
+                  console.log(`::warning::No build.yml run for ${tag} yet after 2 min.`);
+                  console.log(`::warning::If the Gitea post-receive hook is broken, dispatch`);
+                  console.log(`::warning::"Build and Push Images" by hand with ref=${tag}.`);
+                }
+                await sleep(15_000);
+              }
+
+              if (!run) {
+                console.log(`::error::No build.yml run for ${tag} (${sha}) after 20 min.`);
+                console.log(`::error::Dispatch "Build and Push Images" with ref=${tag} (the`);
+                console.log(`::error::tag, not master), then deploy by hand with tag=${version}.`);
+                process.exit(1);
+              }
+
+              const result = outcome(run);
+              if (result !== "success") {
+                console.log(`::error::build.yml for ${tag} ended as "${result}" — not deploying.`);
+                console.log(`::error::Fix the build, re-run it, then deploy by hand with tag=${version}.`);
+                process.exit(1);
+              }
+
+              console.log(`build.yml for ${tag} is green (run ${run.id}). Deploying ${version}.`);
+              const before = await deployRunIds();
+
+              // Dispatch against the TAG, not master: the deploy applies the
+              // compose files under deploy/galactus/ from whatever ref it runs
+              // on, and those must be the ones this release was cut with.
+              const res = await fetch(
+                `${base}/actions/workflows/deploy-galactus.yml/dispatches`,
+                {
+                  method: "POST",
+                  headers: { ...headers, "Content-Type": "application/json" },
+                  body: JSON.stringify({
+                    ref: tagRef,
+                    inputs: {
+                      tag: version,
+                      scope: "app",
+                      bootstrap: "false",
+                      skip_migrate: "false",
+                    },
+                  }),
+                },
+              );
+              if (!res.ok) {
+                console.log(`::error::Dispatch returned HTTP ${res.status}: ${await res.text()}`);
+                console.log(`::error::Images for ${version} are published. Run`);
+                console.log(`::error::"Deploy to galactus" by hand with tag=${version}.`);
+                process.exit(1);
+              }
+
+              // A 204 only means Gitea accepted the request. Confirm a NEW run
+              // exists — an accepted call that creates no run is the failure mode
+              // that cost v1.0.3 its images.
+              for (let i = 0; i < 3; i++) {
+                await sleep(5_000);
+                const fresh = [...(await deployRunIds())].filter((id) => !before.has(id));
+                if (fresh.length) {
+                  console.log(`Deploy of ${version} to galactus is running (run ${fresh[0]}).`);
+                  return;
+                }
+              }
+
+              console.log(`::error::Dispatch was accepted but no deploy run appeared.`);
+              console.log(`::error::Run "Deploy to galactus" by hand with tag=${version}.`);
+              process.exit(1);
+            })();
+          '

.gitea/workflows/deploy.yml

@@ -12,6 +12,7 @@
 # git tag v1.2.3 into image tag 1.2.3. Tag v1.2.3, dispatch 1.2.3.
 #
 # Order: db+minio (full only) -> pre-migrate backup -> prisma migrate deploy ->
+# (the api container also migrates at start; see docker/api-entrypoint.sh)
 # app -> verify the API reports the version you asked for. Rollback = dispatch
 # an older tag; that rolls back CODE only, never the schema, which is why every
 # schema change must be expand/contract. See docs/DEPLOY_AND_MIGRATIONS.md.
@@ -47,9 +48,11 @@
 #      # Database stack (full only)
 #      MYSQL_PASSWORD             app-user password (matches DATABASE_URL)
 #      MYSQL_ROOT_PASSWORD        mysql root password
-#  - the runner must reach BOTH Portainer (9443) and MySQL (3306) — the
+#  - the runner must reach Portainer (9443). It should also reach MySQL (3306)
-#    migration step connects to the database directly. If it cannot reach 3306,
+#    for the migrate step, but that is no longer load-bearing: dispatch with
-#    migrate by hand and dispatch with skip_migrate=true.
+#    skip_migrate=true and the api container applies the migrations itself at
+#    start (docker/api-entrypoint.sh). `migrate deploy` is idempotent, so the
+#    two never conflict.
 #  - ONE-TIME on a database built with `prisma db push` (i.e. every database
 #    that exists today): baseline it before the first run, or the migrate step
 #    fails with P3005 "database schema is not empty":
@@ -79,7 +82,7 @@ on:
         required: false
         default: false
       skip_migrate:
-        description: "Skip prisma migrate deploy (use when the runner cannot reach MySQL and you migrated by hand)"
+        description: "Skip the runner-side migrate step (safe: the api container migrates at start)"
         type: boolean
         required: false
         default: false
@@ -253,13 +256,19 @@ jobs:
           type: file
           pull: true
           endpoint: ${{ secrets.PORTAINER_ENDPOINT_ID }}
+          # NOTE: the block below is parsed as JSON — no comments inside it.
+          #
+          # API_ORIGIN is deliberately absent. The browser derives the API origin
+          # from the page it loaded (apps/web/src/lib/api.ts), so the deployment
+          # survives the host moving. Setting it here would pin it again and
+          # re-break an https front door with mixed active content. APP_API_ORIGIN
+          # lives on only as the URL the verify step probes.
           env_data: |
             {
               "APP_TAG": "${{ github.event.inputs.tag }}",
               "API_PORT": "3001",
               "WEB_PORT": "3000",
               "S3_BUCKET": "jorgecuadros-documents",
-              "API_ORIGIN": "${{ secrets.APP_API_ORIGIN }}",
               "WEB_ORIGIN": "${{ secrets.APP_WEB_ORIGIN }}",
               "S3_ENDPOINT": "${{ secrets.APP_S3_ENDPOINT }}",
               "DATABASE_URL": "${{ secrets.DATABASE_URL }}",
@@ -288,6 +297,12 @@ jobs:
         run: |
           set -e
           apk add --no-cache curl >/dev/null
+          # These secrets are CORS origin LISTS as far as the app is concerned
+          # (WEB_ORIGIN is comma-separated so one deployment can be reached under
+          # several origins at once). A list is not a URL, so probe the FIRST
+          # entry — keep the runner-reachable origin first.
+          API_ORIGIN=${API_ORIGIN%%,*}
+          WEB_ORIGIN=${WEB_ORIGIN%%,*}
           fetch_version() {
             for i in $(seq 1 30); do
               if curl -fsS "$1/version" > "$2"; then return 0; fi

.gitea/workflows/release.yml

@@ -1,10 +1,16 @@
 # Cut a release: stamp the version across every package.json, commit, tag, push.
 #
-# This does NOT build and does NOT deploy. Pushing the `vX.Y.Z` tag is what
+# This does NOT build and does NOT deploy itself. Pushing the `vX.Y.Z` tag is
-# triggers build.yml, which publishes `X.Y.Z`, `X.Y`, `sha-<short>` and `latest`
+# what triggers both build.yml, which publishes the `X.Y.Z`, `X.Y`,
-# image tags. Deploying stays a separate, deliberate act: once the build is
+# `sha-<short>` and `latest` image tags, and deploy-on-tag.yml, which waits for
-# green, dispatch deploy-galactus.yml with `tag=X.Y.Z` (no leading v — the tag
+# that build to go green and then dispatches deploy-galactus.yml with
-# carries the `v`, the image tag does not).
+# `tag=X.Y.Z scope=app` (no leading v — the git tag carries the `v`, the image
+# tag does not). A tag is the only ref that starts either chain; pushing to
+# master builds images and stops there.
+#
+# So cutting a release DOES reach prod. To cut a version without deploying it,
+# set the repo variable AUTO_DEPLOY_GALACTUS=false first; deploy-on-tag.yml then
+# prints the manual command instead of running it.
 #
 # Why a workflow instead of three local commands: the release commit is the one
 # thing that must be identical every time, and cutting it from a laptop is how
@@ -266,5 +272,9 @@ jobs:
           echo "Released v${VERSION}."
           echo ""
           echo "build.yml is now building git.mancinas.io/rmancinas/jorgecuadros-{api,web}:${VERSION}."
-          echo "When it is green, dispatch 'Deploy to galactus' with:"
+          echo "deploy-on-tag.yml is watching that build; when it goes green it dispatches"
-          echo "  tag=${VERSION}  scope=app  bootstrap=false  skip_migrate=false"
+          echo "'Deploy to galactus' with tag=${VERSION} scope=app bootstrap=false skip_migrate=false."
+          echo ""
+          echo "Watch that run. If it did not start (or AUTO_DEPLOY_GALACTUS=false),"
+          echo "dispatch 'Deploy to galactus' by hand with the same inputs."
+          echo "Rollback = re-dispatch it with an older tag."

README.md

@@ -96,7 +96,14 @@ NEXT_PUBLIC_API_ORIGIN=http://localhost:3001
 ```
 
 The API loads `DATABASE_URL`, `SESSION_SECRET`, `WEB_ORIGIN`, and optional
-`PORT` (default `3001`). The web app only needs `NEXT_PUBLIC_API_ORIGIN`.
+`PORT` (default `3001`). `WEB_ORIGIN` is comma-separated — list every origin the
+app is reached under, or credentialed fetches from the missing ones fail CORS.
+
+The web app needs no API URL of its own: the browser derives it from the page it
+loaded (same host on port `3001` over plain HTTP, or the same-origin `/api` path
+behind a TLS proxy). Set `NEXT_PUBLIC_API_ORIGIN` (dev) or `API_ORIGIN` (deploy,
+read at request time) only to override that — for instance when running the API
+on a non-default port.
 
 ### 3. Start MySQL
 

apps/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jorgecuadros/api",
-  "version": "1.0.7",
+  "version": "1.0.25",
   "private": true,
   "scripts": {
     "build": "nest build",

apps/api/src/auth/abilities.ts

@@ -21,6 +21,7 @@ export type Ability =
   | "customer:create"
   | "customer:update"
   | "customer:delete"
+  | "customer:portal-access"
   | "policy:create"
   | "policy:update"
   | "policy:delete"
@@ -48,6 +49,12 @@ export const ABILITY_MIN: Record<Ability, Role> = {
   "customer:create": "STAFF",
   "customer:update": "STAFF",
   "customer:delete": "ADMIN",
+  // Assigning a portal NUMid is granting someone the ability to log in to
+  // my.jorgecuadros.com and read an account, so it sits above customer:update:
+  // editing a phone number is the day job, handing out portal identity is not.
+  // It is also close to irreversible in practice — the id is what the customer
+  // then types at every login.
+  "customer:portal-access": "MANAGER",
   "policy:create": "STAFF",
   "policy:update": "STAFF",
   "policy:delete": "MANAGER",

apps/api/src/billing/balance-floor.spec.ts

@@ -0,0 +1,203 @@
+import { Prisma } from "@jorgecuadros/database";
+import {
+  BALANCE_FLOOR_JOIN,
+  BALANCE_FORWARD_TYPE,
+  BillingService,
+  NOT_SUPERSEDED,
+} from "./billing.service";
+
+/**
+ * The balance floor drops rows a later BALANCE FORWARD already accounts for.
+ *
+ * It is worth testing because it fails silently: nothing throws, the numbers are
+ * just wrong, and they were wrong for years — the whole book read +20.6M MXN in
+ * credit because every customer's pre-cutover history was counted twice, once
+ * inside their opening balance and once as itself.
+ */
+describe("balance floor", () => {
+  describe("SQL fragments", () => {
+    it("binds the type name rather than interpolating it", () => {
+      // A literal would be a second place to edit if the label ever changes,
+      // and this string reaches SQL from a module constant.
+      expect(BALANCE_FLOOR_JOIN.values).toEqual([BALANCE_FORWARD_TYPE]);
+    });
+
+    it("keys the floor to the row's own customer", () => {
+      // Without this the derived table cross-joins and every customer inherits
+      // the earliest BALANCE FORWARD in the book.
+      expect(BALANCE_FLOOR_JOIN.sql).toContain(
+        "bfloor ON bfloor.customerId = t.customerId",
+      );
+    });
+
+    it("takes the most recent opening balance, not the first", () => {
+      // A customer accumulates one BALANCE FORWARD per year. MIN would floor at
+      // the oldest and leave every intervening year double-counted.
+      expect(BALANCE_FLOOR_JOIN.sql).toContain("MAX(bf.transactionDate)");
+      expect(BALANCE_FLOOR_JOIN.sql).not.toContain("MIN(bf.transactionDate)");
+    });
+
+    it("ignores voided opening balances when locating the floor", () => {
+      expect(BALANCE_FLOOR_JOIN.sql).toContain("bf.voidedAt IS NULL");
+    });
+
+    it("is inclusive of the opening balance row itself", () => {
+      // `>` instead of `>=` would drop the carried balance and understate every
+      // customer by exactly that amount.
+      expect(NOT_SUPERSEDED.sql).toContain("t.transactionDate >= bfloor.floorDate");
+      expect(NOT_SUPERSEDED.sql).not.toMatch(/transactionDate\s*>\s*bfloor/);
+    });
+
+    it("leaves customers with no opening balance untouched", () => {
+      // NULL comparisons are never true, so without the explicit IS NULL branch
+      // a customer who has no BALANCE FORWARD row loses their entire ledger.
+      expect(NOT_SUPERSEDED.sql).toContain("bfloor.floorDate IS NULL");
+    });
+
+    it("only ever references the alias the join defines", () => {
+      // The predicate is useless without the join; pairing them wrongly is a
+      // runtime "unknown column", so keep the alias identical in both.
+      const aliases = NOT_SUPERSEDED.sql.match(/bfloor\.\w+/g) ?? [];
+      expect(aliases.length).toBeGreaterThan(0);
+      for (const ref of aliases) {
+        expect(BALANCE_FLOOR_JOIN.sql).toContain(ref.split(".")[1]);
+      }
+    });
+  });
+
+  describe("statement()", () => {
+    /**
+     * One customer means one floor date, so the statement uses a scalar lookup
+     * instead of the join. Asserting on the `where` Prisma is handed is the only
+     * way to see it without a database.
+     */
+    function serviceWith(floor: Date | null) {
+      const findMany = jest.fn().mockResolvedValue([]);
+      const prisma = {
+        customer: {
+          findUnique: jest.fn().mockResolvedValue({
+            id: "c1",
+            name: "CUADROS, JORGE H.",
+            preferredCurrency: "USD",
+            _count: { properties: 0, policies: 0 },
+          }),
+        },
+        transaction: {
+          findFirst: jest
+            .fn()
+            .mockResolvedValue(floor ? { transactionDate: floor } : null),
+          findMany,
+        },
+      };
+
+      return {
+        service: new BillingService(prisma as never),
+        prisma,
+        findMany,
+      };
+    }
+
+    it("looks the floor up from the customer's newest opening balance", async () => {
+      const { service, prisma } = serviceWith(new Date("2026-01-01T00:00:00Z"));
+
+      await service.statement("c1");
+
+      expect(prisma.transaction.findFirst).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: {
+            customerId: "c1",
+            voidedAt: null,
+            type: { nameEn: BALANCE_FORWARD_TYPE },
+          },
+          orderBy: { transactionDate: "desc" },
+          select: { transactionDate: true },
+        }),
+      );
+    });
+
+    /**
+     * statement() issues two findMany calls: first the period discovery (which
+     * years this customer has an archive for), then the statement rows. Select
+     * the rows query by its shape so adding another lookup later moves nothing
+     * here — the previous version indexed call 0 and broke the moment period
+     * support landed.
+     */
+    function rowsQuery(findMany: jest.Mock) {
+      const call = findMany.mock.calls.find((c) => c[0]?.orderBy);
+      if (!call) throw new Error("statement() issued no ordered rows query");
+      return call[0];
+    }
+
+    it("bounds the statement at the floor, inclusive", async () => {
+      const floor = new Date("2026-01-01T00:00:00Z");
+      const { service, findMany } = serviceWith(floor);
+
+      await service.statement("c1");
+
+      expect(rowsQuery(findMany).where).toMatchObject({
+        customerId: "c1",
+        transactionDate: { gte: floor },
+      });
+    });
+
+    it("applies no date bound when the customer has no opening balance", async () => {
+      const { service, findMany } = serviceWith(null);
+
+      await service.statement("c1");
+
+      expect(rowsQuery(findMany).where).not.toHaveProperty("transactionDate");
+    });
+
+    it("keeps the source-table exclusion alongside the floor", async () => {
+      // The two guards answer different questions — one reproduces legacy's
+      // DATOS2-only materialization, the other drops superseded history — and
+      // dropping either one changes the customer's balance.
+      const { service, findMany } = serviceWith(new Date("2026-01-01T00:00:00Z"));
+
+      await service.statement("c1");
+
+      const where = rowsQuery(findMany).where;
+      expect(where.OR).toEqual([
+        { legacySourceTable: null },
+        { legacySourceTable: { notIn: expect.arrayContaining(["EFECTIVO"]) } },
+      ]);
+      // Imported periods are windowed rather than excluded: history below the
+      // year start (the only carry a floored-by-archive customer has), never
+      // at or above it (those rows sit inside the next BALANCE FORWARD).
+      expect(where.AND).toEqual([
+        {
+          OR: [
+            { legacySourceTable: null },
+            { legacySourceTable: { not: { startsWith: "datos2@" } } },
+            { transactionDate: { lt: expect.any(Date) } },
+          ],
+        },
+      ]);
+    });
+  });
+
+  describe("regression: NUMid 501", () => {
+    /**
+     * The arithmetic that exposed the bug, pinned so it cannot silently return.
+     * Figures measured against the live ledger on 2026-08-05.
+     */
+    const openingBalance = new Prisma.Decimal("-6732.29");
+    const activitySinceOpening = new Prisma.Decimal("-7333.00");
+    const preCutoverCashAlreadyInOpening = new Prisma.Decimal("3596.00");
+
+    it("matches the legacy portal once superseded rows are dropped", () => {
+      expect(openingBalance.plus(activitySinceOpening).toFixed(2)).toBe(
+        "-14065.29",
+      );
+    });
+
+    it("reproduces the wrong figure when they are not", () => {
+      expect(
+        openingBalance
+          .plus(activitySinceOpening)
+          .plus(preCutoverCashAlreadyInOpening)
+          .toFixed(2),
+      ).toBe("-10469.29");
+    });
+  });
+});

apps/api/src/billing/billing.controller.ts

@@ -119,10 +119,23 @@ export class BillingController {
     return this.billing.byCheck(n);
   }
 
-  /** One customer's full statement across both business lines. */
+  /**
+   * One customer's statement across both business lines, for one period.
+   *
+   * `year` omitted means the current one. Any earlier year is served from its
+   * imported archive; the response carries `availableYears` so the caller can
+   * offer only the periods this customer actually has.
+   */
   @Get("customers/:id")
-  statement(@Param("id") id: string) {
+  statement(@Param("id") id: string, @Query("year") year?: string) {
-    return this.billing.statement(id);
+    let parsed: number | undefined;
+    if (year !== undefined && year !== "") {
+      parsed = Number(year);
+      if (!Number.isInteger(parsed)) {
+        throw new BadRequestException("year debe ser un año de cuatro dígitos");
+      }
+    }
+    return this.billing.statement(id, parsed);
   }
 
   /** Cross-customer movement browser. */

apps/api/src/billing/billing.service.ts

@@ -104,24 +104,31 @@ interface BalanceRow {
   nameMissing: number;
   city: string | null;
   state: string | null;
-  movements: bigint | number | string;
+  movements: RawCount;
   balanceMxn: Prisma.Decimal | null;
   balanceUsd: Prisma.Decimal | null;
   chargesMxn: Prisma.Decimal | null;
   creditsMxn: Prisma.Decimal | null;
   chargesUsd: Prisma.Decimal | null;
   creditsUsd: Prisma.Decimal | null;
-  utilityMovements: bigint | number | string;
+  utilityMovements: RawCount;
-  insuranceMovements: bigint | number | string;
+  insuranceMovements: RawCount;
   lastMovement: Date | null;
 }
 
 /**
- * Raw-query counts come back in three shapes depending on the aggregate:
+ * Every shape a raw-query count can arrive in. `COUNT(*)` is a bigint,
- * `COUNT(*)` as bigint, `SUM(bool)` as a decimal *string*, and plain numbers.
+ * `SUM(bool)` is a Prisma.Decimal, and plain numbers occur too — none of which
- * Normalize all of them before they reach the client as JSON.
+ * survive JSON serialization the way the client expects.
  */
-function num(v: bigint | number | string | null | undefined): number {
+type RawCount = bigint | number | string | Prisma.Decimal;
+
+/**
+ * Normalizes a raw-query count before it reaches the client as JSON. A bigint
+ * throws on JSON.stringify and a Decimal serializes to a *string*, so counts
+ * must not be passed through untouched.
+ */
+function num(v: RawCount | null | undefined): number {
   if (v === null || v === undefined) return 0;
   return typeof v === "number" ? v : Number(v);
 }
@@ -152,6 +159,56 @@ const NOT_VOIDED: Prisma.TransactionWhereInput = { voidedAt: null };
  */
 const NOT_OUTSTANDING: Prisma.TransactionWhereInput = { outstanding: false };
 
+/**
+ * The legacy type name for a carried-forward opening balance.
+ *
+ * These rows are not movements. Access materialized one per customer per year,
+ * dated Jan 1, holding the closing balance of everything before it — that is
+ * what let the portal keep each year in its own table (`datosfreak` = current,
+ * `2025`, `2024`, ...) and still show a correct running balance from a single
+ * year's rows.
+ */
+export const BALANCE_FORWARD_TYPE = "BALANCE FORWARD";
+
+/**
+ * Per-customer date of the most recent BALANCE FORWARD row.
+ *
+ * Joined rather than correlated: one small derived table (1,170 rows) beats a
+ * subquery evaluated per ledger row.
+ */
+export const BALANCE_FLOOR_JOIN = Prisma.sql`
+  LEFT JOIN (
+    SELECT bf.customerId, MAX(bf.transactionDate) AS floorDate
+    FROM transactions bf
+    JOIN type_transactions bft ON bft.id = bf.typeId
+    WHERE bft.nameEn = ${BALANCE_FORWARD_TYPE} AND bf.voidedAt IS NULL
+    GROUP BY bf.customerId
+  ) bfloor ON bfloor.customerId = t.customerId`;
+
+/**
+ * Excludes rows a later BALANCE FORWARD already accounts for.
+ *
+ * WHY THIS EXISTS. The platform holds both the synthetic BALANCE FORWARD rows
+ * and the real pre-cutover history they summarize, so summing a customer's
+ * whole ledger counts that history twice — once inside the opening balance,
+ * once as itself. NUMid 501 read -10,469.29 on the worklist against -14,065.29
+ * on the customer's own statement and on the legacy portal, the gap being two
+ * cash receipts from 2009 and 2012 that the 2026 opening balance had already
+ * absorbed.
+ *
+ * The scale is what settles it: summed the old way the entire book came to
+ * +20,605,447.86 MXN — the office owing its customers 20.6 million pesos.
+ * Floored, it is -56,855.90, a modest net receivable. A receivables ledger
+ * cannot be 20M in credit.
+ *
+ * Applies to BALANCES ONLY, in the same spirit as NOT_OUTSTANDING: the movement
+ * browser still totals every captured row, because "how much water did we
+ * capture in April" is a question about what was recorded, not about what is
+ * owed. Customers with no BALANCE FORWARD row (the floor is NULL) are
+ * unaffected.
+ */
+export const NOT_SUPERSEDED = Prisma.sql`(bfloor.floorDate IS NULL OR t.transactionDate >= bfloor.floorDate)`;
+
 /**
  * Source tables excluded from the customer-facing statement.
  *
@@ -164,7 +221,21 @@ const NOT_OUTSTANDING: Prisma.TransactionWhereInput = { outstanding: false };
  * browser keep them — they're real money, just tracked separately
  * (FM3 = visa fee stream, EFECTIVO = cash receipt stream).
  */
-const STATEMENT_EXCLUDED_SOURCE_TABLES: readonly string[] = [
+/**
+ * `legacySourceTable` of an imported prior period.
+ *
+ * A closed year arrives as its own Access snapshot and is tagged rather than
+ * dated (see migration/transform_transactions.py). The tag is what a period
+ * view filters on: the archives are not cleanly date-bounded — 2025 carries
+ * rows dated into 2026 — and legacy did not filter by date either, it selected
+ * `FROM \`2025\``. Filtering on provenance reproduces the legacy period exactly.
+ */
+export const periodSourceTable = (year: number) => `datos2@${year}`;
+
+/** Matches any imported period tag, for discovering which years a customer has. */
+export const PERIOD_TABLE_PREFIX = "datos2@";
+
+export const STATEMENT_EXCLUDED_SOURCE_TABLES: readonly string[] = [
   "EFECTIVO",
   "EFECTIVO_BACKUP",
   "EFECTIVO FM3",
@@ -402,22 +473,24 @@ export class BillingService {
         MAX(t.transactionDate)                                                     AS lastMovement
       FROM customers c
       JOIN transactions t ON t.customerId = c.id
-      WHERE t.voidedAt IS NULL AND t.outstanding = 0 ${nameFilter} ${txFilter}
+      ${BALANCE_FLOOR_JOIN}
+      WHERE t.voidedAt IS NULL AND t.outstanding = 0 AND ${NOT_SUPERSEDED} ${nameFilter} ${txFilter}
       GROUP BY c.id, c.name, c.nameSource, c.nameMissing, c.city, c.state
       ${having}
       ${orderBy}
       LIMIT ${pageSize} OFFSET ${(page - 1) * pageSize}
     `;
 
-    const counted = await this.prisma.$queryRaw<{ total: bigint | number | string }[]>`
+    const counted = await this.prisma.$queryRaw<{ total: RawCount }[]>`
       SELECT COUNT(*) AS total FROM (
         SELECT c.id
         FROM customers c
         JOIN transactions t ON t.customerId = c.id
+        ${BALANCE_FLOOR_JOIN}
         -- Must match the page query's filters exactly, or the total disagrees
         -- with the rows. (The void exclusion was missing here before the
         -- outstanding work; a voided-only customer inflated the count.)
-        WHERE t.voidedAt IS NULL AND t.outstanding = 0 ${nameFilter} ${txFilter}
+        WHERE t.voidedAt IS NULL AND t.outstanding = 0 AND ${NOT_SUPERSEDED} ${nameFilter} ${txFilter}
         GROUP BY c.id
         ${having}
       ) x
@@ -458,9 +531,18 @@ export class BillingService {
     };
   }
 
-  /** Top-line figures for the billing page header. */
+  /**
+   * Top-line figures for the billing page header.
+   *
+   * Two different questions live here and they use different row sets.
+   * `movements`, `ledgerCustomers`, `crossLineCustomers` and the date range are
+   * INVENTORY — what is stored — and count everything not voided. Everything
+   * under `byCurrency` / `byDomain` is a BALANCE, so it applies NOT_SUPERSEDED
+   * and drops rows an opening balance already accounts for. The four aggregates
+   * moved from Prisma groupBy to raw SQL to express that join; groupBy cannot.
+   */
   async stats() {
-    const [movements, ledgerCustomers, byCurrency, byDomain] = await Promise.all([
+    const [movements, ledgerCustomers] = await Promise.all([
       this.prisma.transaction.count({ where: NOT_VOIDED }),
       this.prisma.transaction
         .findMany({
@@ -469,34 +551,47 @@ export class BillingService {
           select: { customerId: true },
         })
         .then((r) => r.length),
-      this.prisma.transaction.groupBy({
-        by: ["currency"],
-        where: NOT_VOIDED,
-        _sum: { amount: true },
-        _count: { _all: true },
-      }),
-      this.prisma.transaction.groupBy({
-        by: ["domain", "currency"],
-        where: NOT_VOIDED,
-        _sum: { amount: true },
-        _count: { _all: true },
-      }),
     ]);
 
-    const charges = await this.prisma.transaction.groupBy({
+    const byCurrency = await this.prisma.$queryRaw<
-      by: ["currency"],
+      {
-      where: { AND: [{ amount: { lt: 0 } }, NOT_VOIDED] },
+        currency: string;
-      _sum: { amount: true },
+        net: Prisma.Decimal | null;
-      _count: { _all: true },
+        count: RawCount;
-    });
+        charges: Prisma.Decimal | null;
-    const credits = await this.prisma.transaction.groupBy({
+        chargeCount: RawCount;
-      by: ["currency"],
+        credits: Prisma.Decimal | null;
-      where: { AND: [{ amount: { gt: 0 } }, NOT_VOIDED] },
+        creditCount: RawCount;
-      _sum: { amount: true },
+      }[]
-      _count: { _all: true },
+    >`
-    });
+      SELECT t.currency                                             AS currency,
-    const chargeMap = new Map(charges.map((c) => [c.currency, c]));
+             SUM(t.amount)                                          AS net,
-    const creditMap = new Map(credits.map((c) => [c.currency, c]));
+             COUNT(*)                                               AS count,
+             SUM(CASE WHEN t.amount < 0 THEN t.amount ELSE 0 END)   AS charges,
+             SUM(t.amount < 0)                                      AS chargeCount,
+             SUM(CASE WHEN t.amount > 0 THEN t.amount ELSE 0 END)   AS credits,
+             SUM(t.amount > 0)                                      AS creditCount
+      FROM transactions t
+      ${BALANCE_FLOOR_JOIN}
+      WHERE t.voidedAt IS NULL AND ${NOT_SUPERSEDED}
+      GROUP BY t.currency
+    `;
+
+    const byDomain = await this.prisma.$queryRaw<
+      {
+        domain: string;
+        currency: string;
+        net: Prisma.Decimal | null;
+        count: RawCount;
+      }[]
+    >`
+      SELECT t.domain AS domain, t.currency AS currency,
+             SUM(t.amount) AS net, COUNT(*) AS count
+      FROM transactions t
+      ${BALANCE_FLOOR_JOIN}
+      WHERE t.voidedAt IS NULL AND ${NOT_SUPERSEDED}
+      GROUP BY t.domain, t.currency
+    `;
 
     // How many customers sit on each side of the line, per currency — the
     // headline for a receivables view. Counted in SQL; a customer can be
@@ -504,16 +599,19 @@ export class BillingService {
     const sides = await this.prisma.$queryRaw<
       {
         currency: string;
-        owing: bigint | number | string;
+        owing: RawCount;
-        inCredit: bigint | number | string;
+        inCredit: RawCount;
       }[]
     >`
       SELECT currency,
              SUM(bal < -0.005) AS owing,
              SUM(bal >  0.005) AS inCredit
       FROM (
-        SELECT customerId, currency, SUM(amount) AS bal
+        SELECT t.customerId, t.currency, SUM(t.amount) AS bal
-        FROM transactions WHERE voidedAt IS NULL GROUP BY customerId, currency
+        FROM transactions t
+        ${BALANCE_FLOOR_JOIN}
+        WHERE t.voidedAt IS NULL AND ${NOT_SUPERSEDED}
+        GROUP BY t.customerId, t.currency
       ) x
       GROUP BY currency
     `;
@@ -534,7 +632,7 @@ export class BillingService {
 
     // Customers whose ledger spans both business lines — the whole reason this
     // module is one view instead of two.
-    const crossLine = await this.prisma.$queryRaw<{ n: bigint | number | string }[]>`
+    const crossLine = await this.prisma.$queryRaw<{ n: RawCount }[]>`
       SELECT COUNT(*) AS n FROM (
         SELECT customerId FROM transactions WHERE voidedAt IS NULL
         GROUP BY customerId HAVING COUNT(DISTINCT domain) > 1
@@ -549,20 +647,20 @@ export class BillingService {
       lastMovement: lastRow?.transactionDate ?? null,
       byCurrency: byCurrency.map((c) => ({
         currency: c.currency,
-        net: c._sum.amount,
+        net: c.net,
-        count: c._count._all,
+        count: num(c.count),
-        charges: chargeMap.get(c.currency)?._sum.amount ?? null,
+        charges: c.charges,
-        chargeCount: chargeMap.get(c.currency)?._count._all ?? 0,
+        chargeCount: num(c.chargeCount),
-        credits: creditMap.get(c.currency)?._sum.amount ?? null,
+        credits: c.credits,
-        creditCount: creditMap.get(c.currency)?._count._all ?? 0,
+        creditCount: num(c.creditCount),
         owing: num(sideMap.get(c.currency)?.owing),
         inCredit: num(sideMap.get(c.currency)?.inCredit),
       })),
       byDomain: byDomain.map((d) => ({
         domain: d.domain,
         currency: d.currency,
-        net: d._sum.amount,
+        net: d.net,
-        count: d._count._all,
+        count: num(d.count),
       })),
     };
   }
@@ -589,7 +687,7 @@ export class BillingService {
     });
 
     const years = await this.prisma.$queryRaw<
-      { year: number; count: bigint | number | string }[]
+      { year: number; count: RawCount }[]
     >`
       SELECT YEAR(transactionDate) AS year, COUNT(*) AS count
       FROM transactions WHERE voidedAt IS NULL GROUP BY year ORDER BY year DESC
@@ -617,13 +715,22 @@ export class BillingService {
   /**
    * One customer's statement across both business lines.
    *
-   * Returns the *whole* ledger rather than a page of it: the heaviest customer
+   * Scoped to one calendar year and listed oldest-first, matching the legacy
+   * EDO CUENTA report the office has printed for years: an opening balance at
+   * the top, then the year's movements in the order they happened.
+   *
+   * `year` selects the period. The current year is read from the live tables;
+   * any earlier year is read from its imported archive, which legacy kept as a
+   * separate table and this reads by its `datos2@YYYY` tag. `availableYears`
+   * reports which periods this customer actually has, so a caller never offers
+   * a year that would render empty.
+   *
+   * Returns the *whole* year rather than a page of it: the heaviest customer
    * carries 365 movements (mean 26), and a running balance is meaningless if
    * the client only holds a slice. The running balance is accumulated per
-   * currency in chronological order, then the list is handed back newest-first
+   * currency in chronological order, with each row's balance-after attached.
-   * with each row's balance-after already attached.
    */
-  async statement(customerId: string) {
+  async statement(customerId: string, year?: number) {
     const customer = await this.prisma.customer.findUnique({
       where: { id: customerId },
       select: {
@@ -647,23 +754,126 @@ export class BillingService {
       throw new NotFoundException(`Customer ${customerId} not found`);
     }
 
+    // Which periods this customer has. The current year is always offered —
+    // it is the live ledger even when empty — and each imported archive adds
+    // the year it holds.
+    const archives = await this.prisma.transaction.findMany({
+      where: {
+        customerId,
+        voidedAt: null,
+        legacySourceTable: { startsWith: PERIOD_TABLE_PREFIX },
+      },
+      distinct: ["legacySourceTable"],
+      select: { legacySourceTable: true },
+    });
+    const thisYear = new Date().getUTCFullYear();
+    const archiveYears = archives
+      .map((a) => Number(a.legacySourceTable?.slice(PERIOD_TABLE_PREFIX.length)))
+      .filter((y) => Number.isInteger(y) && y < thisYear);
+    const availableYears = [...new Set([thisYear, ...archiveYears])].sort(
+      (a, b) => b - a,
+    );
+
+    // An unknown year would silently render as the current one, which reads as
+    // "this customer had no activity in 2019" rather than "there is no 2019".
+    const requested = year ?? thisYear;
+    if (!availableYears.includes(requested)) {
+      throw new NotFoundException(
+        `El cliente no tiene movimientos del periodo ${requested}.`,
+      );
+    }
+    const isArchive = requested !== thisYear;
+
+    //
+    // Deliberately open-ended at the top. A period is a table in legacy, not a
+    // date range, so whatever the office filed in it belongs to it — including
+    // the future-dated rows the current ledger carries (it runs to 2028). An
+    // upper bound would hide them from every view, which is not what legacy did
+    // and not what the office has been reading.
+    //
+    // An archive needs no fold at all: it *is* the period, and its own Jan-1
+    // BALANCE FORWARD row is the carry, listed exactly as legacy listed it.
+    const yearStart = isArchive
+      ? new Date(0)
+      : new Date(Date.UTC(requested, 0, 1));
+
+    // One customer, so the balance floor is a single date rather than the
+    // derived table the aggregate queries join. See NOT_SUPERSEDED: rows before
+    // the opening balance are already inside it, and showing them would both
+    // double the total and make every balanceAfter below wrong.
+    //
+    // This is also what stops FEE ANUAL and fee15 leaking in. They are not in
+    // STATEMENT_EXCLUDED_SOURCE_TABLES — that list exists to reproduce legacy's
+    // DATOS2-only `datosfreak`, and it was letting 2,092 pre-cutover fee rows
+    // across 1,062 customers through, skewing the statement by -5,129,764
+    // against the number those customers have been quoted for years. Dating
+    // rather than source is the right test: a FEE ANUAL row *after* the opening
+    // balance is a real charge and still counts.
+    const floor = await this.prisma.transaction.findFirst({
+      where: {
+        customerId,
+        voidedAt: null,
+        type: { nameEn: BALANCE_FORWARD_TYPE },
+      },
+      orderBy: { transactionDate: "desc" },
+      select: { transactionDate: true },
+    });
+
     const rows = await this.prisma.transaction.findMany({
       where: {
         customerId,
-        // NULL-safe exclusion. `notIn` alone compiles to SQL `NOT IN`, and
+        ...(isArchive
-        // `NULL NOT IN (...)` is NULL, not true — so every app-captured row
+          ? // An archive is already exactly one period's ledger, so the tag is
-        // (which has no legacySourceTable) silently vanished from the
+            // the whole filter. The balance floor is deliberately NOT applied:
-        // statement while still showing in the movement browser. Rows the app
+            // it exists to stop a later opening balance double-counting the
-        // books must appear on the customer's statement, so the null case is
+            // history it summarizes, and here that history is the thing being
-        // spelled out.
+            // asked for. The exclusion list is moot too — an archive holds only
-        OR: [
+            // DATOS2 rows, which is what legacy's year table held.
-          { legacySourceTable: null },
+            { legacySourceTable: periodSourceTable(requested) }
-          {
+          : {
-            legacySourceTable: {
+              ...(floor ? { transactionDate: { gte: floor.transactionDate } } : {}),
-              notIn: STATEMENT_EXCLUDED_SOURCE_TABLES as string[],
+              // NULL-safe exclusion. `notIn` alone compiles to SQL `NOT IN`, and
-            },
+              // `NULL NOT IN (...)` is NULL, not true — so every app-captured row
-          },
+              // (which has no legacySourceTable) silently vanished from the
-        ],
+              // statement while still showing in the movement browser. Rows the app
+              // books must appear on the customer's statement, so the null case is
+              // spelled out.
+              OR: [
+                { legacySourceTable: null },
+                {
+                  legacySourceTable: {
+                    notIn: STATEMENT_EXCLUDED_SOURCE_TABLES as string[],
+                  },
+                },
+              ],
+              // An archive row belongs to this period only as history. Below
+              // the year start it is exactly what `opening` is for, and for the
+              // one customer whose newest BALANCE FORWARD lives *inside* an
+              // archive it is the only carry there is — dropping it outright
+              // understated NUMid 295 by his whole 2025 closing balance, 785.46.
+              //
+              // At or above the year start it must go. The archives spill a
+              // couple of rows into the following January, and those are
+              // already inside the next year's BALANCE FORWARD (which is the
+              // sum of the whole archive), so listing them here would both
+              // double-count and file a closed year's row as current.
+              //
+              // Spelled as a positive OR because `NOT (col LIKE ... AND ...)`
+              // is NULL for an app-captured row, which would drop every one.
+              AND: [
+                {
+                  OR: [
+                    { legacySourceTable: null },
+                    {
+                      legacySourceTable: {
+                        not: { startsWith: PERIOD_TABLE_PREFIX },
+                      },
+                    },
+                    { transactionDate: { lt: yearStart } },
+                  ],
+                },
+              ],
+            }),
       },
       orderBy: [{ transactionDate: "asc" }, { id: "asc" }],
       select: {
@@ -683,15 +893,50 @@ export class BillingService {
       },
     });
 
+    // The statement covers one calendar year. The floor above normally lands on
+    // January 1st of it already — the legacy publish writes one BALANCE FORWARD
+    // per customer per year — in which case nothing extra is dropped here. When
+    // it doesn't (a customer the last publish skipped, or one that never had an
+    // opening balance), the earlier rows still have to be *counted* or every
+    // balance below is wrong, so they are folded into `opening` rather than
+    // listed. That is the same thing a BALANCE FORWARD row does, just computed.
     const running = new Map<string, Prisma.Decimal>();
-    const movements = rows.map((r) => {
+    /** Balance carried into `yearStart`, per currency. */
+    const opening = new Map<string, Prisma.Decimal>();
+    /** The same carried balance split by business line, keyed `domain|currency`. */
+    const openingByDomain = new Map<
+      string,
+      { domain: TransactionDomain; currency: string; amount: Prisma.Decimal }
+    >();
+    /** The rows the statement lists — this year's. Totals are built from these. */
+    const visible: typeof rows = [];
+
+    const movements = rows.flatMap((r) => {
       const voided = r.voidedAt != null;
       const prev = running.get(r.currency) ?? new Prisma.Decimal(0);
       // Neither a voided row nor an outstanding (unpaid) one moves the running
       // balance — both show tagged, with the balance unchanged from the previous
       // live movement. Outstanding rows start counting once resolved.
-      const next = voided || r.outstanding ? prev : prev.plus(r.amount);
+      const counted = !voided && !r.outstanding;
+      const next = counted ? prev.plus(r.amount) : prev;
       running.set(r.currency, next);
+
+      if (r.transactionDate < yearStart) {
+        if (counted) {
+          opening.set(r.currency, next);
+          const dk = `${r.domain}|${r.currency}`;
+          const od = openingByDomain.get(dk) ?? {
+            domain: r.domain,
+            currency: r.currency,
+            amount: new Prisma.Decimal(0),
+          };
+          od.amount = od.amount.plus(r.amount);
+          openingByDomain.set(dk, od);
+        }
+        return [];
+      }
+
+      visible.push(r);
       return {
         id: r.id,
         transactionDate: r.transactionDate,
@@ -711,7 +956,6 @@ export class BillingService {
         balanceAfter: next.toFixed(2),
       };
     });
-    movements.reverse();
 
     // Per-currency summary, and the same split by business line so the two
     // ledgers are visibly one statement without being illegally added up.
@@ -739,7 +983,29 @@ export class BillingService {
       }
     >();
 
-    for (const r of rows) {
+    for (const [currency] of opening) {
+      perCurrency.set(currency, {
+        currency,
+        charges: new Prisma.Decimal(0),
+        credits: new Prisma.Decimal(0),
+        chargeCount: 0,
+        creditCount: 0,
+        count: 0,
+        first: null,
+        last: null,
+      });
+    }
+    for (const [key, o] of openingByDomain) {
+      perDomain.set(key, {
+        domain: o.domain,
+        currency: o.currency,
+        charges: new Prisma.Decimal(0),
+        credits: new Prisma.Decimal(0),
+        count: 0,
+      });
+    }
+
+    for (const r of visible) {
       // Voided rows never enter a total; outstanding rows don't either until
       // they're resolved (legacy SALDOS ULTIMO 0's `HAVING NOPAGO = 0`).
       if (r.voidedAt != null || r.outstanding) continue;
@@ -789,7 +1055,7 @@ export class BillingService {
       string,
       { name: string; currency: string; total: Prisma.Decimal; count: number }
     >();
-    for (const r of rows) {
+    for (const r of visible) {
       if (r.voidedAt != null || r.outstanding) continue;
       if (!r.amount.lessThan(0)) continue;
       const name = r.type?.nameEs || r.type?.nameEn || "Sin clasificar";
@@ -808,25 +1074,38 @@ export class BillingService {
         propertyCount: customer._count.properties,
         policyCount: customer._count.policies,
       },
-      summary: [...perCurrency.values()].map((c) => ({
+      year: requested,
-        currency: c.currency,
+      availableYears,
-        charges: c.charges.toFixed(2),
+      summary: [...perCurrency.values()].map((c) => {
-        credits: c.credits.toFixed(2),
+        const open = opening.get(c.currency) ?? new Prisma.Decimal(0);
-        balance: c.charges.plus(c.credits).toFixed(2),
+        return {
-        chargeCount: c.chargeCount,
+          currency: c.currency,
-        creditCount: c.creditCount,
+          /** Balance carried in from before this year — legacy's BALANCE FORWARD. */
-        count: c.count,
+          opening: open.toFixed(2),
-        firstMovement: c.first,
+          charges: c.charges.toFixed(2),
-        lastMovement: c.last,
+          credits: c.credits.toFixed(2),
-      })),
+          balance: open.plus(c.charges).plus(c.credits).toFixed(2),
-      byDomain: [...perDomain.values()].map((d) => ({
+          chargeCount: c.chargeCount,
-        domain: d.domain,
+          creditCount: c.creditCount,
-        currency: d.currency,
+          count: c.count,
-        charges: d.charges.toFixed(2),
+          firstMovement: c.first,
-        credits: d.credits.toFixed(2),
+          lastMovement: c.last,
-        balance: d.charges.plus(d.credits).toFixed(2),
+        };
-        count: d.count,
+      }),
-      })),
+      byDomain: [...perDomain.values()].map((d) => {
+        const open =
+          openingByDomain.get(`${d.domain}|${d.currency}`)?.amount ??
+          new Prisma.Decimal(0);
+        return {
+          domain: d.domain,
+          currency: d.currency,
+          opening: open.toFixed(2),
+          charges: d.charges.toFixed(2),
+          credits: d.credits.toFixed(2),
+          balance: open.plus(d.charges).plus(d.credits).toFixed(2),
+          count: d.count,
+        };
+      }),
       byType: [...byType.values()]
         .map((t) => ({
           name: t.name,

apps/api/src/billing/statement-period.spec.ts

@@ -0,0 +1,36 @@
+import { periodSourceTable } from "./billing.service";
+
+/**
+ * A closed year is imported as its own tagged set of rows rather than being
+ * identified by date. The tag is written by migration/transform_transactions.py
+ * and read by BillingService.statement, the edo-cuenta-datos report, and the
+ * PHP portal — three places that must agree on the exact string.
+ */
+describe("periodSourceTable", () => {
+  it("names the archive the migration writes", () => {
+    expect(periodSourceTable(2025)).toBe("datos2@2025");
+    expect(periodSourceTable(2024)).toBe("datos2@2024");
+  });
+
+  it("stays distinct from the live ledger's own table", () => {
+    // The live table is plain `datos2`. legacyId is a positional ordinal that
+    // restarts at 0 in every archive, so a shared name would collide with the
+    // current year row-for-row on the unique key.
+    expect(periodSourceTable(2025)).not.toBe("datos2");
+    expect(periodSourceTable(2025).startsWith("datos2@")).toBe(true);
+  });
+
+  it("is not matched by the statement's cash-source exclusion list", () => {
+    // STATEMENT_EXCLUDED_SOURCE_TABLES drops the EFECTIVO family to reproduce
+    // legacy's DATOS2-only datosfreak. An archive holds DATOS2 rows, so it must
+    // survive that filter or a prior year renders empty.
+    const excluded = [
+      "EFECTIVO",
+      "EFECTIVO_BACKUP",
+      "EFECTIVO FM3",
+      "CHEQUE FM3",
+      "IVA 2015",
+    ];
+    expect(excluded).not.toContain(periodSourceTable(2025));
+  });
+});

apps/api/src/billing/statement-year.spec.ts

@@ -0,0 +1,145 @@
+import { Prisma } from "@jorgecuadros/database";
+import { BillingService } from "./billing.service";
+
+/**
+ * The statement is a *year* statement, like the EDO CUENTA report the office
+ * prints: this year's movements, oldest-first, opening on the balance carried
+ * in from before it.
+ *
+ * The carrying is the part worth testing. Dropping earlier rows from the list
+ * is easy; dropping them from the arithmetic too would restart every balance at
+ * zero on January 1st, and nothing would throw — the numbers would just be
+ * wrong, which is exactly how the double-counting bug lived for years.
+ */
+describe("statement year scoping", () => {
+  const YEAR = new Date().getUTCFullYear();
+
+  function d(iso: string) {
+    return new Date(`${iso}T00:00:00.000Z`);
+  }
+
+  type RowSpec = {
+    id: string;
+    date: Date;
+    amount: string;
+    currency?: string;
+    domain?: string;
+    voidedAt?: Date | null;
+    outstanding?: boolean;
+  };
+
+  function row(r: RowSpec) {
+    return {
+      id: r.id,
+      transactionDate: r.date,
+      domain: r.domain ?? "UTILITY",
+      amount: new Prisma.Decimal(r.amount),
+      currency: r.currency ?? "MXN",
+      reference: null,
+      period: null,
+      checkNumber: null,
+      message: null,
+      legacySourceTable: null,
+      voidedAt: r.voidedAt ?? null,
+      outstanding: r.outstanding ?? false,
+      type: { nameEn: "WATER", nameEs: "AGUA" },
+    };
+  }
+
+  /** No BALANCE FORWARD row, so the floor is null and every row is fetched. */
+  function serviceWith(rows: RowSpec[]) {
+    const prisma = {
+      customer: {
+        findUnique: jest.fn().mockResolvedValue({
+          id: "c1",
+          name: "CUADROS, JORGE H.",
+          preferredCurrency: "MXN",
+          _count: { properties: 0, policies: 0 },
+        }),
+      },
+      transaction: {
+        findFirst: jest.fn().mockResolvedValue(null),
+        findMany: jest.fn().mockResolvedValue(rows.map(row)),
+      },
+    };
+    return new BillingService(prisma as never);
+  }
+
+  it("lists the year's movements oldest-first", async () => {
+    const s = await serviceWith([
+      { id: "a", date: d(`${YEAR}-01-02`), amount: "-100" },
+      { id: "b", date: d(`${YEAR}-03-04`), amount: "250" },
+      { id: "c", date: d(`${YEAR}-07-16`), amount: "-40" },
+    ]).statement("c1");
+
+    expect(s.movements.map((m) => m.id)).toEqual(["a", "b", "c"]);
+  });
+
+  it("leaves earlier years off the list", async () => {
+    const s = await serviceWith([
+      { id: "old", date: d(`${YEAR - 1}-11-30`), amount: "-500" },
+      { id: "new", date: d(`${YEAR}-02-11`), amount: "-100" },
+    ]).statement("c1");
+
+    expect(s.movements.map((m) => m.id)).toEqual(["new"]);
+  });
+
+  it("carries the earlier years' balance instead of discarding it", async () => {
+    // 1,000 credit left over from last year, 300 charged this year: the
+    // customer is 700 in credit, not 300 in debt.
+    const s = await serviceWith([
+      { id: "old", date: d(`${YEAR - 1}-12-15`), amount: "1000" },
+      { id: "new", date: d(`${YEAR}-02-11`), amount: "-300" },
+    ]).statement("c1");
+
+    const mxn = s.summary.find((x) => x.currency === "MXN");
+    expect(mxn?.opening).toBe("1000.00");
+    expect(mxn?.charges).toBe("-300.00");
+    expect(mxn?.balance).toBe("700.00");
+    // The running balance on the listed row picks up where last year left off.
+    expect(s.movements[0].balanceAfter).toBe("700.00");
+  });
+
+  it("carries it per business line as well", async () => {
+    const s = await serviceWith([
+      { id: "old", date: d(`${YEAR - 1}-12-15`), amount: "1000", domain: "INSURANCE" },
+      { id: "new", date: d(`${YEAR}-02-11`), amount: "-300", domain: "INSURANCE" },
+    ]).statement("c1");
+
+    const line = s.byDomain.find((x) => x.domain === "INSURANCE");
+    expect(line?.opening).toBe("1000.00");
+    expect(line?.balance).toBe("700.00");
+  });
+
+  it("still reports a currency that only moved in earlier years", async () => {
+    // Otherwise a customer sitting on a dollar credit they haven't touched all
+    // year would appear to have no dollar balance at all.
+    const s = await serviceWith([
+      { id: "old", date: d(`${YEAR - 2}-05-01`), amount: "180.83", currency: "USD" },
+      { id: "new", date: d(`${YEAR}-02-11`), amount: "-300" },
+    ]).statement("c1");
+
+    const usd = s.summary.find((x) => x.currency === "USD");
+    expect(usd?.balance).toBe("180.83");
+    expect(usd?.count).toBe(0);
+  });
+
+  it("does not carry a voided earlier row", async () => {
+    const s = await serviceWith([
+      { id: "old", date: d(`${YEAR - 1}-12-15`), amount: "1000", voidedAt: d(`${YEAR - 1}-12-16`) },
+      { id: "new", date: d(`${YEAR}-02-11`), amount: "-300" },
+    ]).statement("c1");
+
+    const mxn = s.summary.find((x) => x.currency === "MXN");
+    expect(mxn?.opening).toBe("0.00");
+    expect(mxn?.balance).toBe("-300.00");
+  });
+
+  it("reports the year it covers", async () => {
+    const s = await serviceWith([
+      { id: "a", date: d(`${YEAR}-01-02`), amount: "-100" },
+    ]).statement("c1");
+
+    expect(s.year).toBe(YEAR);
+  });
+});

apps/api/src/customers/customer-ledger-card.spec.ts

@@ -0,0 +1,122 @@
+import { CustomersService } from "./customers.service";
+import { BALANCE_FORWARD_TYPE } from "../billing/billing.service";
+
+/**
+ * The /clientes/:id ledger card is titled "Estado de cuenta" and links straight
+ * to the statement, so its per-line totals must be the statement's numbers.
+ *
+ * They were a raw lifetime sum — no floor, no source exclusion — which
+ * double-counted the pre-cutover history each BALANCE FORWARD row absorbs.
+ * Importing prior periods made it visibly worse: every closed year is now held
+ * a second time as its own tagged copy, so an unfloored sum adds each one on
+ * top of the opening balance that already contains it.
+ */
+describe("customer file ledger card", () => {
+  function serviceWith(floor: Date | null) {
+    const groupBy = jest.fn().mockResolvedValue([]);
+    const prisma = {
+      customer: {
+        findUnique: jest.fn().mockResolvedValue({ id: "c1", transactions: [] }),
+      },
+      transaction: {
+        findFirst: jest
+          .fn()
+          .mockResolvedValue(floor ? { transactionDate: floor } : null),
+        groupBy,
+      },
+    };
+    return {
+      service: new CustomersService(prisma as never),
+      prisma,
+      groupBy,
+    };
+  }
+
+  it("takes the same balance floor the statement takes", async () => {
+    const floor = new Date("2026-01-01T00:00:00Z");
+    const { service, prisma, groupBy } = serviceWith(floor);
+
+    await service.detail("c1");
+
+    expect(prisma.transaction.findFirst).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: expect.objectContaining({
+          type: { nameEn: BALANCE_FORWARD_TYPE },
+        }),
+      }),
+    );
+    expect(groupBy.mock.calls[0][0].where).toMatchObject({
+      transactionDate: { gte: floor },
+    });
+  });
+
+  it("applies no floor when the customer never had an opening balance", async () => {
+    // 102 customers have no BALANCE FORWARD row at all. Inventing a floor for
+    // them would hide their whole ledger.
+    const { service, groupBy } = serviceWith(null);
+
+    await service.detail("c1");
+
+    expect(groupBy.mock.calls[0][0].where).not.toHaveProperty("transactionDate");
+  });
+
+  it("counts an archive as history but never as current", async () => {
+    // The floor alone is not enough: a customer floored by an archive clears
+    // it with every row of that archive, and the rows archives spill into the
+    // following January clear any floor. But excluding archives outright is
+    // wrong too — below the year start they are the only carry a
+    // floored-by-archive customer has (NUMid 295, 785.46).
+    const { service, groupBy } = serviceWith(new Date("2026-01-01T00:00:00Z"));
+
+    await service.detail("c1");
+
+    const and = groupBy.mock.calls[0][0].where.AND;
+    const rule = and.find((c: { OR?: unknown[] }) =>
+      JSON.stringify(c).includes("datos2@"),
+    );
+    expect(rule.OR).toEqual([
+      { legacySourceTable: null },
+      { legacySourceTable: { not: { startsWith: "datos2@" } } },
+      { transactionDate: { lt: expect.any(Date) } },
+    ]);
+  });
+
+  it("keeps the cash-source exclusion so it reads like the statement", async () => {
+    const { service, groupBy } = serviceWith(new Date("2026-01-01T00:00:00Z"));
+
+    await service.detail("c1");
+
+    const and = groupBy.mock.calls[0][0].where.AND;
+    const sourceRule = and.find((c: { OR?: unknown[] }) =>
+      JSON.stringify(c).includes("EFECTIVO"),
+    );
+    expect(sourceRule).toBeDefined();
+  });
+
+  it("drops outstanding rows, as every balance does", async () => {
+    const { service, groupBy } = serviceWith(null);
+
+    await service.detail("c1");
+
+    expect(groupBy.mock.calls[0][0].where).toMatchObject({
+      outstanding: false,
+    });
+  });
+
+  it("keeps archives out of the year's movement list too", async () => {
+    // datos2@2024 carries rows dated into 2026; a date test alone would show
+    // them as current-year movements next to the live ledger's own copy.
+    const { service, prisma } = serviceWith(null);
+
+    await service.detail("c1");
+
+    const include = prisma.customer.findUnique.mock.calls[0][0].include;
+    expect(include.transactions.where.OR).toEqual([
+      { legacySourceTable: null },
+      { legacySourceTable: { not: { startsWith: "datos2@" } } },
+      // Nothing below yearStart reaches this list, so the third branch never
+      // admits an archive row here — it is carried for one shared rule.
+      { transactionDate: { lt: expect.any(Date) } },
+    ]);
+  });
+});

apps/api/src/customers/customers.controller.ts

@@ -16,6 +16,7 @@ import { AbilityGuard } from "../auth/ability.guard";
 import { RequireAbility } from "../auth/require-ability.decorator";
 import { AuditService } from "../common/audit.service";
 import { CustomersService } from "./customers.service";
+import { NumidService } from "./numid.service";
 import { CreateCustomerDto } from "./create-customer.dto";
 import { UpdateCustomerDto } from "./update-customer.dto";
 
@@ -24,6 +25,7 @@ import { UpdateCustomerDto } from "./update-customer.dto";
 export class CustomersController {
   constructor(
     private readonly customers: CustomersService,
+    private readonly numids: NumidService,
     private readonly audit: AuditService,
   ) {}
 
@@ -36,6 +38,13 @@ export class CustomersController {
     return this.customers.stats();
   }
 
+  /** Reusable portal ids, lowest first. Declared above `:id` so the literal
+   *  path is not swallowed by the wildcard route. */
+  @Get("numid/candidates")
+  async numidCandidates() {
+    return { candidates: await this.numids.emptyCandidates() };
+  }
+
   @Get()
   list(
     @Query("query") query?: string,
@@ -95,4 +104,27 @@ export class CustomersController {
     void this.audit.log(this.actingId(req), "customer.restore", { customerId: id });
     return c;
   }
+
+  /**
+   * Give this customer a portal NUMid so they can log in to
+   * my.jorgecuadros.com. Idempotent — a customer who already has one gets it
+   * back rather than a second identity.
+   */
+  @Post(":id/portal-access")
+  @RequireAbility("customer:portal-access")
+  async portalAccess(@Param("id") id: string, @Req() req: Request) {
+    const allocation = await this.numids.allocate(id);
+    if (allocation.origin !== "existing") {
+      // Logged with the origin and the previous holder: a recycled id is the one
+      // case where reading this record later has to answer "whose number was
+      // this before, and was it taken or minted".
+      void this.audit.log(this.actingId(req), "customer.portal-access", {
+        customerId: id,
+        numid: allocation.numid,
+        origin: allocation.origin,
+        previousCustomerId: allocation.previousCustomerId,
+      });
+    }
+    return allocation;
+  }
 }

apps/api/src/customers/customers.module.ts

@@ -1,9 +1,13 @@
 import { Module } from "@nestjs/common";
+import { SettingsModule } from "../settings/settings.module";
 import { CustomersController } from "./customers.controller";
 import { CustomersService } from "./customers.service";
+import { NumidService } from "./numid.service";
 
 @Module({
+  imports: [SettingsModule],
   controllers: [CustomersController],
-  providers: [CustomersService],
+  providers: [CustomersService, NumidService],
+  exports: [NumidService],
 })
 export class CustomersModule {}

apps/api/src/customers/customers.service.ts

@@ -3,6 +3,46 @@ import { Prisma } from "@jorgecuadros/database";
 import { PrismaService } from "../prisma/prisma.service";
 import { CreateCustomerDto } from "./create-customer.dto";
 import { UpdateCustomerDto } from "./update-customer.dto";
+import {
+  BALANCE_FORWARD_TYPE,
+  PERIOD_TABLE_PREFIX,
+  STATEMENT_EXCLUDED_SOURCE_TABLES,
+} from "../billing/billing.service";
+
+/**
+ * Keeps imported prior periods out of a query, NULL-safely.
+ *
+ * A closed year is imported as its own tagged copy of that year's ledger
+ * (`datos2@2025`) and the BALANCE FORWARD rows above it already contain every
+ * peso of it. Anything summing a customer's history has to leave the archives
+ * out or it counts each closed year twice — see the floor comment below.
+ *
+ * `NULL NOT LIKE '...'` is NULL rather than true, so app-captured rows (which
+ * carry no legacySourceTable) need the null branch spelled out or they vanish.
+ */
+/**
+ * Keeps an imported prior period out of the *current* period, NULL-safely.
+ *
+ * A closed year is imported as its own tagged copy (`datos2@2025`). Below the
+ * year start it is history and counts — for the one customer whose newest
+ * BALANCE FORWARD lives inside an archive it is the only carry there is, and
+ * dropping it understated NUMid 295 by his entire 2025 closing balance. At or
+ * above the year start it must go: the archives spill a couple of rows into the
+ * following January, and those already sit inside the next year's BALANCE
+ * FORWARD, which is the sum of the whole archive.
+ *
+ * Spelled as a positive OR because `NOT (col LIKE ... AND ...)` evaluates to
+ * NULL for an app-captured row (no legacySourceTable), dropping every one.
+ */
+const archiveIsHistory = (
+  yearStart: Date,
+): Prisma.TransactionWhereInput => ({
+  OR: [
+    { legacySourceTable: null },
+    { legacySourceTable: { not: { startsWith: PERIOD_TABLE_PREFIX } } },
+    { transactionDate: { lt: yearStart } },
+  ],
+});
 
 export interface ListParams {
   query?: string;
@@ -96,6 +136,13 @@ export class CustomersService {
 
   /** Full unified customer view: identity + both business lines + ledger. */
   async detail(id: string) {
+    // The movement list on the customer file is the same statement the office
+    // prints, so it follows the same rule as BillingService.statement: this
+    // calendar year, oldest-first. No `take` any more — the cap used to hide
+    // the end of a busy customer's year once the order flipped, and a single
+    // year is small (365 rows for the heaviest customer in the book).
+    const yearStart = new Date(Date.UTC(new Date().getUTCFullYear(), 0, 1));
+
     const customer = await this.prisma.customer.findUnique({
       where: { id },
       include: {
@@ -117,8 +164,21 @@ export class CustomersService {
           },
         },
         transactions: {
-          orderBy: { transactionDate: "desc" },
+          // Archives are excluded by tag, not by date. They are not cleanly
-          take: 100,
+          // bounded — datos2@2024 carries rows dated 2022, 2023, 2025 and one
+          // in 2026, datos2@2025 two more — so a date test alone would surface
+          // a closed year's rows in the current year's list, duplicating the
+          // live ledger's own copy of them for three customers.
+          // Archives are kept out by tag, not by date. They are not cleanly
+          // bounded — datos2@2025 carries rows dated into 2026 — so a date test
+          // alone would surface a closed year's rows in the current year's
+          // list. Nothing below yearStart reaches this list anyway, so the
+          // window rule reduces to a plain exclusion here.
+          where: {
+            transactionDate: { gte: yearStart },
+            ...archiveIsHistory(yearStart),
+          },
+          orderBy: [{ transactionDate: "asc" }, { id: "asc" }],
           include: { type: true },
         },
       },
@@ -130,16 +190,63 @@ export class CustomersService {
 
     // Ledger totals per domain + currency (the "one statement across both
     // business lines" payoff), computed in the DB rather than in JS.
+    //
+    // These have to answer the same question BillingService.statement answers,
+    // because this card is titled "Estado de cuenta" and links straight to it —
+    // two screens quoting one customer two different balances is worse than
+    // either number alone. So it takes the same three rules the statement uses:
+    // the balance floor, the cash-source exclusion, and dropping outstanding
+    // rows the office has not paid yet.
+    //
+    // Without the floor these were a raw lifetime sum, double-counting the
+    // pre-cutover history each BALANCE FORWARD row already absorbs. Importing
+    // prior periods made that visibly worse: for NUMid 501 the tiles read
+    // -7,119.29 before the archives landed and -15,270.59 after, against a true
+    // -10,715.29 — the difference being exactly the 2024 and 2025 closing
+    // balances, added a second time on top of the opening row that contains
+    // them.
+    const floor = await this.prisma.transaction.findFirst({
+      where: {
+        customerId: id,
+        voidedAt: null,
+        type: { nameEn: BALANCE_FORWARD_TYPE },
+      },
+      orderBy: { transactionDate: "desc" },
+      select: { transactionDate: true },
+    });
+
     const summary = await this.prisma.transaction.groupBy({
       by: ["domain", "currency"],
-      // Exclude voided rows so the per-domain balance matches the statement.
+      where: {
-      where: { customerId: id, voidedAt: null },
+        customerId: id,
+        voidedAt: null,
+        outstanding: false,
+        ...(floor ? { transactionDate: { gte: floor.transactionDate } } : {}),
+        // The floor alone does not settle the archives: a customer floored by
+        // an archive clears it with every row of that archive, and the rows
+        // archives spill into the following January clear any floor.
+        AND: [
+          archiveIsHistory(yearStart),
+          {
+            OR: [
+              { legacySourceTable: null },
+              {
+                legacySourceTable: {
+                  notIn: [...STATEMENT_EXCLUDED_SOURCE_TABLES],
+                },
+              },
+            ],
+          },
+        ],
+      },
       _sum: { amount: true },
       _count: { _all: true },
     });
 
     return {
       ...customer,
+      /** Calendar year the movement list covers. */
+      transactionYear: yearStart.getUTCFullYear(),
       transactionSummary: summary.map((s) => ({
         domain: s.domain,
         currency: s.currency,

apps/api/src/customers/numid.service.spec.ts

@@ -0,0 +1,206 @@
+import { ConflictException, NotFoundException } from "@nestjs/common";
+import { Prisma } from "@jorgecuadros/database";
+import { NumidService } from "./numid.service";
+
+/**
+ * What matters about the allocator is the two things it must never do: hand the
+ * same id to two customers, and hand out a recycled id while Access can still
+ * take it back. Both are tested here; the emptiness SQL itself is exercised
+ * against real data by scripts/numid-audit.mjs.
+ */
+
+interface Options {
+  existingRef?: { legacyId: string } | null;
+  archived?: boolean;
+  missing?: boolean;
+  recycle?: boolean;
+  empty?: { numid: string; refId: string; customerId: string }[];
+  max?: number | null;
+  /** Make the first N create() calls fail the unique key, as a race would. */
+  createConflicts?: number;
+  /** Make updateMany report "nothing matched", as a lost recycle race would. */
+  recycleMisses?: number;
+}
+
+function build(opts: Options = {}) {
+  const created: { legacyId: string }[] = [];
+  let conflictsLeft = opts.createConflicts ?? 0;
+  let missesLeft = opts.recycleMisses ?? 0;
+
+  const prisma = {
+    customer: {
+      findUnique: jest.fn().mockResolvedValue(
+        opts.missing ? null : { id: "cust-new", archivedAt: opts.archived ? new Date() : null },
+      ),
+    },
+    customerLegacyRef: {
+      findFirst: jest.fn().mockResolvedValue(opts.existingRef ?? null),
+      updateMany: jest.fn().mockImplementation(() => {
+        if (missesLeft > 0) {
+          missesLeft -= 1;
+          return Promise.resolve({ count: 0 });
+        }
+        return Promise.resolve({ count: 1 });
+      }),
+      create: jest.fn().mockImplementation(({ data }: { data: { legacyId: string } }) => {
+        if (conflictsLeft > 0) {
+          conflictsLeft -= 1;
+          return Promise.reject(
+            new Prisma.PrismaClientKnownRequestError("dup", {
+              code: "P2002",
+              clientVersion: "5",
+            }),
+          );
+        }
+        created.push(data);
+        return Promise.resolve(data);
+      }),
+    },
+    // Two different raw queries share one mock: the MAX lookup returns a single
+    // {max} row, everything else is the empty-candidate list.
+    $queryRaw: jest.fn().mockImplementation((sql: { strings?: string[]; sql?: string }) => {
+      const text = String((sql as unknown as { sql?: string }).sql ?? "");
+      if (text.includes("MAX(")) return Promise.resolve([{ max: opts.max ?? null }]);
+      return Promise.resolve(opts.empty ?? []);
+    }),
+  };
+
+  const settings = {
+    numidRecycleEmpty: jest
+      .fn()
+      .mockResolvedValue({ value: opts.recycle ?? false, source: "default" }),
+  };
+
+  return {
+    service: new NumidService(prisma as never, settings as never),
+    prisma,
+    created,
+  };
+}
+
+describe("NUMid allocation", () => {
+  it("returns the id a customer already holds instead of minting a second one", async () => {
+    // A double-clicked button must not fork the customer's portal identity.
+    const { service, prisma } = build({ existingRef: { legacyId: "501" } });
+
+    await expect(service.allocate("cust-new")).resolves.toEqual({
+      numid: "501",
+      origin: "existing",
+    });
+    expect(prisma.customerLegacyRef.create).not.toHaveBeenCalled();
+  });
+
+  it("allocates one past the highest id in the pool", async () => {
+    const { service, created } = build({ max: 1171 });
+
+    await expect(service.allocate("cust-new")).resolves.toEqual({
+      numid: "1172",
+      origin: "new",
+    });
+    expect(created[0]).toMatchObject({
+      sourceSystem: "utilities",
+      sourceTable: "DATGRAL",
+      legacyId: "1172",
+    });
+  });
+
+  it("starts at 1 when the pool is empty", async () => {
+    const { service } = build({ max: null });
+
+    await expect(service.allocate("cust-new")).resolves.toMatchObject({ numid: "1" });
+  });
+
+  it("does NOT recycle while the setting is off, even with candidates free", async () => {
+    // The default has to be the safe one: every reusable id still exists in
+    // Access, and a --sync run reassigns it back to its Access owner.
+    const { service, prisma } = build({
+      max: 1171,
+      empty: [{ numid: "1089", refId: "ref-1089", customerId: "cust-old" }],
+    });
+
+    await expect(service.allocate("cust-new")).resolves.toMatchObject({
+      numid: "1172",
+      origin: "new",
+    });
+    expect(prisma.customerLegacyRef.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("takes the lowest empty id once recycling is switched on", async () => {
+    const { service, prisma } = build({
+      recycle: true,
+      max: 1171,
+      empty: [
+        { numid: "1089", refId: "ref-1089", customerId: "cust-old" },
+        { numid: "1094", refId: "ref-1094", customerId: "cust-other" },
+      ],
+    });
+
+    await expect(service.allocate("cust-new")).resolves.toEqual({
+      numid: "1089",
+      origin: "recycled",
+      previousCustomerId: "cust-old",
+    });
+    // Guarded on the owner read a moment ago, so a ref that moved underneath us
+    // matches nothing rather than being stolen.
+    expect(prisma.customerLegacyRef.updateMany).toHaveBeenCalledWith({
+      where: { id: "ref-1089", customerId: "cust-old" },
+      data: { customerId: "cust-new" },
+    });
+  });
+
+  it("skips a candidate that someone else took first", async () => {
+    const { service } = build({
+      recycle: true,
+      max: 1171,
+      recycleMisses: 1,
+      empty: [
+        { numid: "1089", refId: "ref-1089", customerId: "cust-old" },
+        { numid: "1094", refId: "ref-1094", customerId: "cust-other" },
+      ],
+    });
+
+    await expect(service.allocate("cust-new")).resolves.toMatchObject({
+      numid: "1094",
+      origin: "recycled",
+    });
+  });
+
+  it("falls back to a new id when recycling is on but nothing is free", async () => {
+    const { service } = build({ recycle: true, max: 1171, empty: [] });
+
+    await expect(service.allocate("cust-new")).resolves.toMatchObject({
+      numid: "1172",
+      origin: "new",
+    });
+  });
+
+  it("retries when two writers pick the same id", async () => {
+    // The unique key on (sourceSystem, sourceTable, legacyId) is what decides
+    // the winner; the loser must retry, never overwrite.
+    const { service, prisma } = build({ max: 1171, createConflicts: 1 });
+
+    await expect(service.allocate("cust-new")).resolves.toMatchObject({
+      numid: "1172",
+      origin: "new",
+    });
+    expect(prisma.customerLegacyRef.create).toHaveBeenCalledTimes(2);
+  });
+
+  it("gives up loudly rather than looping forever", async () => {
+    const { service } = build({ max: 1171, createConflicts: 99 });
+
+    await expect(service.allocate("cust-new")).rejects.toBeInstanceOf(ConflictException);
+  });
+
+  it("refuses an archived customer", async () => {
+    const { service } = build({ archived: true });
+
+    await expect(service.allocate("cust-new")).rejects.toBeInstanceOf(ConflictException);
+  });
+
+  it("refuses a customer that does not exist", async () => {
+    const { service } = build({ missing: true });
+
+    await expect(service.allocate("nope")).rejects.toBeInstanceOf(NotFoundException);
+  });
+});

apps/api/src/customers/numid.service.ts

@@ -0,0 +1,255 @@
+import {
+  ConflictException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from "@nestjs/common";
+import { Prisma } from "@jorgecuadros/database";
+import { PrismaService } from "../prisma/prisma.service";
+import { SettingsService } from "../settings/settings.service";
+
+/**
+ * Allocation of the portal NUMid — the "Security Number" my.jorgecuadros.com
+ * asks for at login.
+ *
+ * The NUMid is not a column on `Customer`. It is a `CustomerLegacyRef` row with
+ * (sourceSystem='utilities', sourceTable='DATGRAL'), and `CustomersService.create`
+ * deliberately writes none: a natively created customer has no legacy provenance.
+ * The consequence is that every customer created in the staff UI is invisible to
+ * the portal until this service gives them an id.
+ *
+ * WHY THIS IS NOT DONE AT CREATE TIME. Insurance is expected to move to the
+ * platform before utilities, and an insurance-only customer has no reason to hold
+ * a portal identity. Allocating on every create would spend utilities ids — and
+ * the handful of reusable ones — on people who will never log in. So this is an
+ * explicit staff action instead.
+ */
+
+/** The pair that identifies a portal NUMid. */
+export const UTILITIES_SYSTEM = "utilities";
+export const UTILITIES_TABLE = "DATGRAL";
+
+/**
+ * insurance/DATGRAL is a SEPARATE id space that reuses the same sourceTable name
+ * and runs past 4,000. It must never be read as a NUMid, and never allocated
+ * from: the portal cannot resolve those ids. Every query here filters on BOTH
+ * columns for that reason, never on sourceTable alone. A customer can also hold
+ * more than one insurance ref — 16 of them do, where several insurance rows
+ * folded into one customer — so those are tested with EXISTS rather than joined.
+ */
+const POOL = {
+  sourceSystem: UTILITIES_SYSTEM,
+  sourceTable: UTILITIES_TABLE,
+} as const;
+
+export type AllocationOrigin = "existing" | "new" | "recycled";
+
+export interface Allocation {
+  numid: string;
+  origin: AllocationOrigin;
+  /** Set only on a recycle — the customer the id was taken from. */
+  previousCustomerId?: string;
+}
+
+/**
+ * NUMids that were created and never used, safe for an allocator to take.
+ *
+ * THE TWO OBVIOUS RULES BOTH FIND NOTHING, which is why this one looks the way
+ * it does. "Owns no rows" matches nobody: migration gave all 1,171 NUMids a
+ * property and a transaction. "No transaction in N years" also matches nobody:
+ * every customer carries a synthetic Jan-1 opening-balance row, so everyone
+ * looks active in the current year. That row has to be subtracted before any
+ * activity test means anything, which is what `bf` does below.
+ *
+ * The balance-forward row is matched in two shapes on purpose.
+ * transform_transactions.py:120 mints a type literally named 'BALANCE FORWARD';
+ * databases loaded before that change carry the same rows with typeId NULL,
+ * dated Jan 1, legacySourceTable='datos2'. Matching only the type name floors
+ * nothing on such a database and turns the balance test into a raw lifetime sum
+ * — the double-count that read the whole book as +20.6M MXN in credit before
+ * d173c9e, and which here would mark live customers as empty.
+ *
+ * Services are tested as "any service" rather than "any ACTIVE service": a
+ * deactivated water account is still a record of somebody having lived behind
+ * this id.
+ *
+ * Kept in step with scripts/numid-audit.sql, which reports the same tier for a
+ * human. That script is the reporting copy of this rule; change both together.
+ */
+const EMPTY_NUMID_SQL = Prisma.sql`
+  WITH bf AS (
+    SELECT t.id, t.customerId
+    FROM transactions t
+    LEFT JOIN type_transactions tt ON tt.id = t.typeId
+    WHERE t.voidedAt IS NULL
+      AND (
+        tt.nameEn = 'BALANCE FORWARD'
+        OR (t.typeId IS NULL AND MONTH(t.transactionDate) = 1 AND DAY(t.transactionDate) = 1
+            AND t.legacySourceTable = 'datos2')
+      )
+  )
+  SELECT r.legacyId AS numid, r.id AS refId, r.customerId AS customerId
+  FROM customer_legacy_refs r
+  JOIN customers c ON c.id = r.customerId
+  WHERE r.sourceSystem = ${UTILITIES_SYSTEM} AND r.sourceTable = ${UTILITIES_TABLE}
+    AND (c.email IS NULL OR c.email = '')
+    AND NOT EXISTS (SELECT 1 FROM transactions t
+                    WHERE t.customerId = c.id AND t.voidedAt IS NULL
+                      AND t.id NOT IN (SELECT id FROM bf))
+    AND NOT EXISTS (SELECT 1 FROM transactions t
+                    WHERE t.customerId = c.id AND t.voidedAt IS NULL AND t.outstanding = 1)
+    AND NOT EXISTS (SELECT 1 FROM property_services ps
+                    JOIN properties p ON p.id = ps.propertyId WHERE p.customerId = c.id)
+    AND NOT EXISTS (SELECT 1 FROM policies p WHERE p.customerId = c.id)
+    AND NOT EXISTS (SELECT 1 FROM vehicles v WHERE v.customerId = c.id)
+    AND NOT EXISTS (SELECT 1 FROM trust_accounts ta
+                    JOIN properties p ON p.id = ta.propertyId WHERE p.customerId = c.id)
+    AND NOT EXISTS (SELECT 1 FROM statement_documents s WHERE s.matchedCustomerId = c.id)
+    AND NOT EXISTS (SELECT 1 FROM policy_ocr_documents o WHERE o.matchedCustomerId = c.id)
+    AND NOT EXISTS (SELECT 1 FROM email_notification_log e WHERE e.customerId = c.id)
+    AND NOT EXISTS (SELECT 1 FROM email_log e WHERE e.customerId = c.id)
+    AND NOT EXISTS (SELECT 1 FROM account_status_history a WHERE a.customerId = c.id)
+    AND NOT EXISTS (SELECT 1 FROM customer_legacy_refs i
+                    WHERE i.customerId = c.id AND i.sourceSystem = 'insurance')
+  ORDER BY CAST(r.legacyId AS UNSIGNED)`;
+
+interface EmptyRow {
+  numid: string;
+  refId: string;
+  customerId: string;
+}
+
+@Injectable()
+export class NumidService {
+  private readonly logger = new Logger(NumidService.name);
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly settings: SettingsService,
+  ) {}
+
+  /** The customer's portal id, or null if they have none. */
+  async current(customerId: string): Promise<string | null> {
+    const ref = await this.prisma.customerLegacyRef.findFirst({
+      where: { customerId, ...POOL },
+      select: { legacyId: true },
+    });
+    return ref?.legacyId ?? null;
+  }
+
+  /** Reusable ids, lowest first. Empty unless recycling is switched on. */
+  async emptyCandidates(): Promise<string[]> {
+    const rows = await this.prisma.$queryRaw<EmptyRow[]>(EMPTY_NUMID_SQL);
+    return rows.map((r) => r.numid);
+  }
+
+  /**
+   * Give a customer a portal NUMid.
+   *
+   * Idempotent: a customer who already holds one gets it back rather than a
+   * second id, so a double-clicked button cannot fork an identity.
+   */
+  async allocate(customerId: string): Promise<Allocation> {
+    const customer = await this.prisma.customer.findUnique({
+      where: { id: customerId },
+      select: { id: true, archivedAt: true },
+    });
+    if (!customer) throw new NotFoundException(`Customer ${customerId} not found`);
+    if (customer.archivedAt) {
+      throw new ConflictException(
+        "No se puede asignar un número de portal a un cliente archivado",
+      );
+    }
+
+    const existing = await this.current(customerId);
+    if (existing) return { numid: existing, origin: "existing" };
+
+    const recycle = await this.recycleEnabled();
+
+    // Two writers can pick the same id between the read and the write. The
+    // unique key on (sourceSystem, sourceTable, legacyId) is what actually
+    // decides the winner; the loser retries and takes the next id rather than
+    // silently overwriting. Bounded so a genuinely wedged pool fails loudly.
+    for (let attempt = 0; attempt < 5; attempt++) {
+      try {
+        if (recycle) {
+          const recycled = await this.tryRecycle(customerId);
+          if (recycled) return recycled;
+        }
+        return await this.allocateNext(customerId);
+      } catch (error) {
+        if (!isUniqueViolation(error)) throw error;
+        this.logger.warn(
+          `NUMid allocation for ${customerId} lost a race (attempt ${attempt + 1}), retrying`,
+        );
+      }
+    }
+    throw new ConflictException(
+      "No se pudo asignar un número de portal; intente de nuevo",
+    );
+  }
+
+  /**
+   * Whether the recycle tier is live.
+   *
+   * Off by default, and that default is the safe one while Access is still the
+   * utilities master. Every id in the pool ALSO exists in Access DATGRAL, and a
+   * `--sync` migration run upserts refs with ON DUPLICATE KEY UPDATE customerId
+   * (transform_customers.py:327) — so an id recycled today is silently handed
+   * back to its Access owner on the next sync, and the customer who was given it
+   * loses their portal identity. Turn this on once utilities has cut over, or
+   * for ids that have been deleted at the source.
+   */
+  private async recycleEnabled(): Promise<boolean> {
+    const { value } = await this.settings.numidRecycleEmpty();
+    return value;
+  }
+
+  /** Re-point the lowest empty id at this customer. Null when none is free. */
+  private async tryRecycle(customerId: string): Promise<Allocation | null> {
+    const rows = await this.prisma.$queryRaw<EmptyRow[]>(EMPTY_NUMID_SQL);
+    for (const row of rows) {
+      // Guarded by the owner we just read: if anything moved the ref in the
+      // meantime the update matches nothing and we fall through to the next
+      // candidate rather than stealing an id that is no longer empty.
+      const moved = await this.prisma.customerLegacyRef.updateMany({
+        where: { id: row.refId, customerId: row.customerId },
+        data: { customerId },
+      });
+      if (moved.count === 1) {
+        this.logger.log(
+          `NUMid ${row.numid} recycled from ${row.customerId} to ${customerId}`,
+        );
+        return {
+          numid: row.numid,
+          origin: "recycled",
+          previousCustomerId: row.customerId,
+        };
+      }
+    }
+    return null;
+  }
+
+  /** One past the highest id in the pool. */
+  private async allocateNext(customerId: string): Promise<Allocation> {
+    const [{ max }] = await this.prisma.$queryRaw<{ max: number | null }[]>(
+      // MAX over a CAST, not over the string: legacyId is VARCHAR, so a plain
+      // MAX returns '999' as the highest of 1,171 rows and the allocator hands
+      // out an id that is already taken.
+      Prisma.sql`SELECT MAX(CAST(legacyId AS UNSIGNED)) AS max
+                 FROM customer_legacy_refs
+                 WHERE sourceSystem = ${UTILITIES_SYSTEM} AND sourceTable = ${UTILITIES_TABLE}`,
+    );
+    const numid = String(Number(max ?? 0) + 1);
+    await this.prisma.customerLegacyRef.create({
+      data: { customerId, ...POOL, legacyId: numid },
+    });
+    return { numid, origin: "new" };
+  }
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  return (
+    error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2002"
+  );
+}

apps/api/src/main.ts

@@ -60,7 +60,19 @@ async function bootstrap() {
   app.use(passport.initialize());
   app.use(passport.session());
 
-  app.enableCors({ credentials: true, origin: process.env.WEB_ORIGIN ?? "http://localhost:3000" });
+  // The same deployment is reached under several origins — the office LAN IP,
+  // the tailnet name, the demo domain — and the browser derives the API origin
+  // from whichever one served the page (apps/web/src/lib/api.ts). So WEB_ORIGIN
+  // is a comma-separated LIST, not a single value. A request whose Origin is
+  // not listed gets no CORS headers and the credentialed fetch fails, so add an
+  // entry when a new way of reaching the app is introduced. Same-origin setups
+  // (web and API behind one proxy) never hit CORS at all.
+  const webOrigins = (process.env.WEB_ORIGIN ?? "http://localhost:3000")
+    .split(",")
+    .map((o) => o.trim())
+    .filter(Boolean);
+
+  app.enableCors({ credentials: true, origin: webOrigins });
 
   const port = process.env.PORT ? Number(process.env.PORT) : 3001;
   await app.listen(port);

apps/api/src/ops/job-progress.spec.ts

@@ -0,0 +1,76 @@
+import { jobProgress } from "./ops.service";
+
+/** Shape run_all.py emits, with the shell trace lines it interleaves. */
+const line = (i: number, n: number, name: string) =>
+  `[paso ${i}/${n}] ${name}\n+ /repo/migration/.venv/bin/python /repo/migration/${name} --env prod\n[${name}] target env: prod\n  validation: OK`;
+
+describe("jobProgress", () => {
+  it("returns null before any step marker appears", () => {
+    // The safety backup runs before run_all.py, so this is the real state for
+    // the first stretch of every REIMPORT.
+    expect(jobProgress("== Respaldo de seguridad previo ==\ntablas capturadas: 39", "RUNNING")).toBeNull();
+  });
+
+  it("returns null for jobs that have no steps at all", () => {
+    // BACKUP/RESTORE are a single mysqldump; a fabricated percentage would be
+    // worse than none.
+    expect(jobProgress("mysqldump ... done", "SUCCESS")).toBeNull();
+  });
+
+  it("tracks the most recent marker, not the first", () => {
+    const log = [line(1, 9, "transform_customers.py"), line(2, 9, "transform_properties.py")].join("\n");
+    const p = jobProgress(log, "RUNNING");
+    expect(p).toMatchObject({ step: 2, total: 9, name: "transform_properties.py" });
+  });
+
+  /**
+   * The point of the whole feature. While RUNNING, step i is IN PROGRESS, so
+   * only i-1 are done. Counting i as complete would show 100% while the final
+   * and slowest step (blob_extract) is still working.
+   */
+  it("does not claim a running step is finished", () => {
+    expect(jobProgress(line(1, 9, "transform_customers.py"), "RUNNING")?.percent).toBe(0);
+    expect(jobProgress(line(9, 9, "blob_extract.py"), "RUNNING")?.percent).toBe(88);
+  });
+
+  it("reaches 100 only once the job is no longer running", () => {
+    expect(jobProgress(line(9, 9, "blob_extract.py"), "SUCCESS")?.percent).toBe(100);
+  });
+
+  /** A job that died mid-way must report where it died, not 100%. */
+  it("reports the failed step rather than completion", () => {
+    const p = jobProgress(line(5, 9, "transform_transactions.py"), "FAILED");
+    expect(p).toMatchObject({ step: 5, total: 9 });
+    expect(p!.percent).toBe(55);
+  });
+
+  it("handles the 8-step SYNC list as well as the 9-step REIMPORT one", () => {
+    expect(jobProgress(line(8, 8, "transform_bank.py"), "SUCCESS")?.percent).toBe(100);
+    expect(jobProgress(line(4, 8, "transform_policies.py"), "RUNNING")?.percent).toBe(37);
+  });
+
+  /**
+   * Captured verbatim from `run_all.run(..., step=8, total=9)`. This is the
+   * contract between the Python and this parser; if run_all.py's format
+   * changes, this fails rather than the panel silently showing no progress.
+   */
+  it("parses the exact line run_all.py emits", () => {
+    const real =
+      "[paso 8/9] transform_bank.py\n+ /repo/migration/.venv/bin/python /repo/migration/transform_bank.py --env prod";
+    expect(jobProgress(real, "RUNNING")).toMatchObject({
+      step: 8,
+      total: 9,
+      name: "transform_bank.py",
+      percent: 77,
+    });
+  });
+
+  it("ignores a malformed marker instead of reporting NaN", () => {
+    expect(jobProgress("[paso 3/0] x.py", "RUNNING")).toBeNull();
+  });
+
+  /** The marker must be at line start so log text quoting it cannot spoof it. */
+  it("does not match a marker embedded mid-line", () => {
+    expect(jobProgress("some output mentioning [paso 4/9] fake.py", "RUNNING")).toBeNull();
+  });
+});

apps/api/src/ops/ops.controller.ts

@@ -19,6 +19,7 @@ import { AbilityGuard } from "../auth/ability.guard";
 import { RequireAbility } from "../auth/require-ability.decorator";
 import { AuditService } from "../common/audit.service";
 import { OpsService } from "./ops.service";
+import { ReplicationService } from "./replication.service";
 import { StartJobDto } from "./start-job.dto";
 
 /** Every route is ADMIN-only (ability "db:manage"). */
@@ -28,6 +29,7 @@ import { StartJobDto } from "./start-job.dto";
 export class OpsController {
   constructor(
     private readonly ops: OpsService,
+    private readonly replication: ReplicationService,
     private readonly audit: AuditService,
   ) {}
 
@@ -96,6 +98,30 @@ export class OpsController {
 
   /* --------------------------------------------------------------- jobs */
 
+  /** Health of the my.jorgecuadros.com read replica. Read-only, no audit entry. */
+  @Get("replication")
+  replicationStatus() {
+    return this.replication.status();
+  }
+
+  /**
+   * Full row-by-row comparison of the customer-visible tables against the master.
+   *
+   * POST rather than GET despite reading nothing: it is a full scan of both
+   * servers and must not be something a browser prefetch, a retry, or a refresh
+   * can set off. Audited for the same reason — it is a deliberate, costly act,
+   * and "who ran this while the site was slow" is a question worth answering.
+   */
+  @Post("replication/verify")
+  async verifyReplication(@Req() req: Request) {
+    const result = await this.replication.verify();
+    void this.audit.log(this.actingId(req), "ops.replication.verify", {
+      identical: result.identical,
+      elapsedMs: result.elapsedMs,
+    });
+    return result;
+  }
+
   @Get("jobs")
   listJobs() {
     return this.ops.listJobs();
@@ -109,11 +135,17 @@ export class OpsController {
   @Post("jobs")
   async startJob(@Body() dto: StartJobDto, @Req() req: Request) {
     const userId = this.actingId(req);
-    const job = await this.ops.startJob(dto.kind, { file: dto.file }, userId);
+    const job = await this.ops.startJob(
+      dto.kind,
+      { file: dto.file, forceFull: dto.forceFull },
+      userId,
+    );
     void this.audit.log(userId, "ops.job.start", {
       jobId: job.id,
       kind: dto.kind,
       file: dto.file,
+      // Recorded because this is the flag that authorised deleting native rows.
+      forceFull: dto.forceFull,
     });
     return job;
   }

apps/api/src/ops/ops.module.ts

@@ -1,9 +1,10 @@
 import { Module } from "@nestjs/common";
 import { OpsController } from "./ops.controller";
 import { OpsService } from "./ops.service";
+import { ReplicationService } from "./replication.service";
 
 @Module({
   controllers: [OpsController],
-  providers: [OpsService],
+  providers: [OpsService, ReplicationService],
 })
 export class OpsModule {}

apps/api/src/ops/ops.service.ts

@@ -31,6 +31,29 @@ export const INGEST_FILES = [
 ] as const;
 export type IngestName = (typeof INGEST_FILES)[number];
 
+/**
+ * A prior-period archive: one Access snapshot per closed year, named for the
+ * period it holds. `2025.accdb` is UTILITIES as it stood when 2025 was cut.
+ *
+ * The filename is the entire declaration of the period — nothing inside the
+ * file names its year, because a snapshot's `datos2` is indistinguishable from
+ * the live one — so this pattern is both the allowlist and the contract. It is
+ * anchored and allows no separator, which is what keeps an upload from
+ * escaping the ingest directory.
+ */
+const PERIOD_FILE_RE = /^(\d{4})\.accdb$/i;
+
+/** Earliest period we will accept, so a typo'd year cannot mint a bogus one. */
+const PERIOD_MIN_YEAR = 1990;
+
+export function periodYearOf(name: string): number | null {
+  const m = PERIOD_FILE_RE.exec(name);
+  if (!m) return null;
+  const year = Number(m[1]);
+  if (year < PERIOD_MIN_YEAR || year > new Date().getUTCFullYear()) return null;
+  return year;
+}
+
 /**
  * Prefix for every command containing a pipe. Without it the exit status of
  * `mysqldump | gzip` is gzip's, so a dump that failed immediately still looks
@@ -67,23 +90,83 @@ export class OpsService implements OnModuleInit {
   async onModuleInit(): Promise<void> {
     await fs.mkdir(this.ingestDir, { recursive: true });
     await fs.mkdir(this.backupDir, { recursive: true });
+    await this.reconcileOrphanedJobs();
+  }
+
+  /**
+   * Fail any job still marked RUNNING at startup.
+   *
+   * Jobs run as a child of THIS process, so no job can outlive it: if a row says
+   * RUNNING while we are booting, its process died with the previous instance
+   * and nothing will ever finalize it. Since startJob() refuses to start while
+   * any RUNNING row exists, one interrupted job wedges the panel permanently
+   * with no way out from the UI — it took a manual UPDATE against production to
+   * recover the first time this happened, when a deploy landed 110 seconds into
+   * a REIMPORT.
+   *
+   * Deliberately unconditional rather than filtered on age: "started recently"
+   * does not mean "still alive" here, and a fresh boot is proof enough that
+   * nothing survived.
+   */
+  private async reconcileOrphanedJobs(): Promise<void> {
+    try {
+      // Read then write one by one rather than updateMany: the log needs the
+      // reason APPENDED, and a job whose log just stops mid-step with no
+      // explanation is what made the first occurrence hard to diagnose.
+      const orphans = await this.prisma.opsJob.findMany({
+        where: { status: "RUNNING" },
+        select: { id: true, kind: true, log: true },
+      });
+      for (const job of orphans) {
+        await this.prisma.opsJob.update({
+          where: { id: job.id },
+          data: {
+            status: "FAILED",
+            finishedAt: new Date(),
+            log: {
+              set:
+                job.log +
+                "\n[interrumpido: el contenedor se reinició mientras el trabajo corría; " +
+                "el proceso hijo no sobrevive a un redespliegue. " +
+                "Vuelva a ejecutar la operación desde el principio.]\n",
+            },
+          },
+        });
+        this.logger.warn(`trabajo ${job.kind} ${job.id} quedó huérfano; marcado FAILED`);
+      }
+    } catch (e) {
+      // Never block startup on this. A failed reconcile leaves the panel
+      // wedged, which is bad, but an API that will not boot is worse.
+      this.logger.error(`no se pudieron reconciliar trabajos huérfanos: ${String(e)}`);
+    }
   }
 
   /* -------------------------------------------------------------- ingest */
 
-  private assertIngestName(name: string): IngestName {
+  private assertIngestName(name: string): string {
-    if (!INGEST_FILES.includes(name as IngestName)) {
+    if (INGEST_FILES.includes(name as IngestName)) return name;
-      throw new BadRequestException(
+    if (periodYearOf(name) !== null) return name;
-        `Archivo no permitido. Debe ser uno de: ${INGEST_FILES.join(", ")}`,
+    throw new BadRequestException(
-      );
+      `Archivo no permitido. Debe ser uno de: ${INGEST_FILES.join(", ")}` +
-    }
+        `, o un archivo de periodo anterior con nombre AAAA.accdb (por ejemplo 2025.accdb).`,
-    return name as IngestName;
+    );
   }
 
   async listIngest(): Promise<
-    { name: string; present: boolean; size: number | null; modifiedAt: string | null }[]
+    {
+      name: string;
+      present: boolean;
+      size: number | null;
+      modifiedAt: string | null;
+      /** Set only on a prior-period archive; null on the four fixed sources. */
+      periodYear: number | null;
+    }[]
   > {
-    return Promise.all(
+    // The four fixed sources are listed whether present or not — they are
+    // required, so "missing" is the useful state to show. Period archives are
+    // optional and unbounded, so they are listed only once uploaded, newest
+    // year first.
+    const fixed = await Promise.all(
       INGEST_FILES.map(async (name) => {
         try {
           const st = await fs.stat(path.join(this.ingestDir, name));
@@ -92,12 +175,46 @@ export class OpsService implements OnModuleInit {
             present: true,
             size: st.size,
             modifiedAt: st.mtime.toISOString(),
+            periodYear: null as number | null,
           };
         } catch {
-          return { name, present: false, size: null, modifiedAt: null };
+          return {
+            name,
+            present: false,
+            size: null,
+            modifiedAt: null,
+            periodYear: null as number | null,
+          };
         }
       }),
     );
+
+    let entries: string[] = [];
+    try {
+      entries = await fs.readdir(this.ingestDir);
+    } catch {
+      entries = [];
+    }
+    const periods = (
+      await Promise.all(
+        entries
+          .map((name) => ({ name, year: periodYearOf(name) }))
+          .filter((e): e is { name: string; year: number } => e.year !== null)
+          .sort((a, b) => b.year - a.year)
+          .map(async ({ name, year }) => {
+            const st = await fs.stat(path.join(this.ingestDir, name));
+            return {
+              name,
+              present: true,
+              size: st.size,
+              modifiedAt: st.mtime.toISOString(),
+              periodYear: year,
+            };
+          }),
+      )
+    ).filter(Boolean);
+
+    return [...fixed, ...periods];
   }
 
   async saveIngest(name: string, data: Buffer): Promise<void> {
@@ -163,7 +280,9 @@ export class OpsService implements OnModuleInit {
   async getJob(id: string) {
     const job = await this.prisma.opsJob.findUnique({ where: { id } });
     if (!job) throw new NotFoundException("Trabajo no encontrado.");
-    return job;
+    // Derived, never stored: the log is the single source of truth for how far
+    // a job got, so progress cannot drift out of sync with it.
+    return { ...job, progress: jobProgress(job.log, job.status) };
   }
 
   /**
@@ -349,7 +468,12 @@ export class OpsService implements OnModuleInit {
         `${PIPEFAIL}echo '== Respaldo de seguridad previo ==' && ` +
         `${this.dumpCommand(flags, db, out)} && ` +
         `echo '== Sincronización aditiva desde carpeta de ingesta ==' && ` +
-        `${shq(py)} ${runAll} --env ${shq(this.migrationEnv)} --sync`;
+        // --stage is not optional here. The staged Parquet lives in the image
+        // at migration/output, NOT on a volume, so every redeploy wipes it and
+        // a sync without --stage dies on a missing stg_*/*.parquet. Re-staging
+        // is also the only thing that makes "desde carpeta de ingesta" true:
+        // stale Parquet would sync the previous upload, not the current one.
+        `${shq(py)} ${runAll} --env ${shq(this.migrationEnv)} --stage --sync`;
       return { cmd, resolvedParams: { safetyBackup: file } };
     }
 
@@ -359,12 +483,19 @@ export class OpsService implements OnModuleInit {
       const out = shq(path.join(this.backupDir, file));
       const py = await this.pythonBin();
       const runAll = shq(path.join(this.migrationDir, "run_all.py"));
+      // run_all.py runs native_guard.py before it truncates anything and exits
+      // without touching the database when the target holds rows that only
+      // exist here — allocated portal NUMids, app-created customers, OCR
+      // captures. --force-full is what the operator ticks to delete them
+      // anyway; without it the job fails with the list.
+      const force = params.forceFull === true;
       const cmd =
         `${PIPEFAIL}echo '== Respaldo de seguridad previo ==' && ` +
         `${this.dumpCommand(flags, db, out)} && ` +
         `echo '== Reimportación desde carpeta de ingesta ==' && ` +
-        `${shq(py)} ${runAll} --env ${shq(this.migrationEnv)} --stage`;
+        `${shq(py)} ${runAll} --env ${shq(this.migrationEnv)} --stage` +
-      return { cmd, resolvedParams: { safetyBackup: file } };
+        (force ? " --force-full" : "");
+      return { cmd, resolvedParams: { safetyBackup: file, forceFull: force } };
     }
 
     throw new BadRequestException(`Operación no soportada: ${kind}`);
@@ -465,3 +596,52 @@ export class OpsService implements OnModuleInit {
 function shq(v: string): string {
   return `'${v.replace(/'/g, `'\\''`)}'`;
 }
+
+/** Progress derived from a job's log. Null when the job reports no steps. */
+export interface JobProgress {
+  /** 1-based index of the step currently running (or last reached). */
+  step: number;
+  total: number;
+  /** Script name, e.g. "transform_bank.py". */
+  name: string;
+  /** 0..100, floored. 100 only once the job is no longer RUNNING. */
+  percent: number;
+}
+
+/**
+ * Parse the "[paso i/N] name" markers migration/run_all.py emits.
+ *
+ * Progress is DERIVED from the log rather than tracked in a column: the log is
+ * already the record of what happened, and a separate counter could disagree
+ * with it — which is exactly the confusion a progress display is supposed to
+ * remove. run_all.py owns the step count, so adding a step cannot desync this.
+ *
+ * BACKUP and RESTORE are a single mysqldump with no steps, so they return null
+ * and the UI shows an indeterminate spinner. Reporting a fabricated percentage
+ * for them would be worse than showing none.
+ */
+export function jobProgress(
+  log: string,
+  status: string,
+): JobProgress | null {
+  // Last marker wins: the log grows, and the newest line is the current step.
+  const matches = [...log.matchAll(/^\[paso (\d+)\/(\d+)\] (\S+)/gm)];
+  const last = matches[matches.length - 1];
+  if (!last) return null;
+
+  const step = Number(last[1]);
+  const total = Number(last[2]);
+  if (!Number.isFinite(step) || !Number.isFinite(total) || total <= 0) return null;
+
+  // While RUNNING, step i means i is IN PROGRESS, not finished — so report
+  // (i-1) completed. Claiming 100% while the last step is still working is the
+  // classic progress-bar lie, and here the last step (blob_extract) is also the
+  // slowest, so it would sit at "100%" for the longest stretch of the job.
+  const done = status === "RUNNING" ? step - 1 : step;
+  return {
+    step,
+    total,
+    name: last[3],
+    percent: Math.max(0, Math.min(100, Math.floor((done / total) * 100))),
+  };
+}

apps/api/src/ops/period-file.spec.ts

@@ -0,0 +1,48 @@
+import { periodYearOf } from "./ops.service";
+
+/**
+ * `periodYearOf` is the upload allowlist for prior-period archives, so it is
+ * doing two jobs at once: deciding what counts as a period file, and keeping a
+ * caller-supplied name from escaping the ingest directory. Both are pinned here.
+ */
+describe("periodYearOf", () => {
+  it("accepts a four-digit year archive", () => {
+    expect(periodYearOf("2025.accdb")).toBe(2025);
+    expect(periodYearOf("1999.accdb")).toBe(1999);
+  });
+
+  it("is case-insensitive on the extension", () => {
+    expect(periodYearOf("2025.ACCDB")).toBe(2025);
+  });
+
+  it("rejects a path that would escape the ingest directory", () => {
+    // The name is joined onto the ingest path, so anything with a separator or
+    // a parent reference has to fail before it reaches the filesystem.
+    expect(periodYearOf("../2025.accdb")).toBeNull();
+    expect(periodYearOf("../../etc/passwd")).toBeNull();
+    expect(periodYearOf("sub/2025.accdb")).toBeNull();
+    expect(periodYearOf("2025.accdb/../../x")).toBeNull();
+  });
+
+  it("rejects names that only look like a period", () => {
+    expect(periodYearOf("202.accdb")).toBeNull();
+    expect(periodYearOf("20255.accdb")).toBeNull();
+    expect(periodYearOf("2025.mdb")).toBeNull();
+    expect(periodYearOf("copia 2025.accdb")).toBeNull();
+    expect(periodYearOf("2025.accdb.bak")).toBeNull();
+    expect(periodYearOf("UTILITIES.accdb")).toBeNull();
+  });
+
+  it("rejects years outside the plausible range", () => {
+    // A typo'd year would otherwise mint a period nobody can ever reconcile:
+    // there is no BALANCE FORWARD for the year after it to check against.
+    expect(periodYearOf("1889.accdb")).toBeNull();
+    expect(periodYearOf(`${new Date().getUTCFullYear() + 1}.accdb`)).toBeNull();
+  });
+
+  it("accepts the current year, which is the earliest a period can be cut", () => {
+    expect(periodYearOf(`${new Date().getUTCFullYear()}.accdb`)).toBe(
+      new Date().getUTCFullYear(),
+    );
+  });
+});

apps/api/src/ops/replication.service.ts

@@ -0,0 +1,639 @@
+import { Injectable, Logger } from "@nestjs/common";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+
+/**
+ * How far the SQL thread is behind the I/O thread, in source binlog bytes.
+ *
+ * This is a different question from `secondsBehind`, and it answers the case
+ * that lag hides: while the SQL thread grinds through one huge transaction,
+ * `Seconds_Behind_Source` can sit still or even read 0, but the relay backlog
+ * is plainly shrinking (or not). It costs nothing extra — every field here
+ * comes out of the same `SHOW REPLICA STATUS` the panel already runs.
+ *
+ * Both positions are coordinates in the SOURCE's binlog, so they are only
+ * comparable while both threads are working on the SAME source file. When they
+ * are not, the replica is whole files behind and the byte delta is meaningless
+ * (positions restart at ~4 in each new file), so `backlogBytes` and `percent`
+ * are null and `sameFile` says why.
+ */
+export interface ApplyProgress {
+  /** Source binlog file the I/O thread is currently reading. */
+  sourceLogFile: string | null;
+  /** Position in `sourceLogFile` that the I/O thread has fetched up to. */
+  readPos: number;
+  /** Source binlog file the SQL thread is currently applying. */
+  relayLogFile: string | null;
+  /** Position in `relayLogFile` that the SQL thread has applied up to. */
+  execPos: number;
+  /** True while both threads are on the same source file. */
+  sameFile: boolean;
+  /** Fetched-but-not-yet-applied bytes. Null when the files differ. */
+  backlogBytes: number | null;
+  /**
+   * `execPos / readPos` as a percentage, null when the files differ.
+   *
+   * Deliberately never rounded up to 100 while any backlog remains: binlog
+   * positions are large, so a real backlog of a few KB is 99.99% of the file
+   * and would render as "caught up" when it is not. Read `backlogBytes === 0`
+   * for actually caught up.
+   */
+  percent: number | null;
+}
+
+/**
+ * How far the replica's executed history is from the master's, in transactions.
+ *
+ * This is the check `SHOW REPLICA STATUS` cannot give you, and it is stronger
+ * than everything else on the card for one specific reason: every other field is
+ * self-reported by the replica. `Seconds_Behind_Source` reads 0 both when there
+ * is genuinely nothing to apply AND when the I/O thread is disconnected — with
+ * no incoming event there is nothing to measure staleness against, so a dead
+ * link reports as perfectly current. `GTID_SUBTRACT(master, replica)` asks the
+ * master what it has done and the replica what it has applied, so a silent
+ * disconnect shows up immediately as a growing number.
+ */
+export interface GtidDrift {
+  /** Transactions the master executed that the replica has not. 0 = identical. */
+  missingTransactions: number;
+  /** The missing GTID set verbatim. Null when nothing is missing. */
+  missingGtidSet: string | null;
+  /**
+   * Transactions in the replica's `gtid_executed` under its OWN server UUID —
+   * writes that happened here and exist nowhere on the master.
+   *
+   * Reported, never alarmed on. A non-zero count is the expected residue of the
+   * seed load: restoring a dump executes its statements locally, and they take
+   * GTIDs from this server's UUID. They never propagate (`log_replica_updates`
+   * is off and nothing sources from this node), so they are harmless — right up
+   * until someone tries to promote this box, where they become a real divergence.
+   */
+  localTransactions: number;
+}
+
+/** One table's row count and content fingerprint, on one side of the link. */
+export interface TableFingerprint {
+  table: string;
+  masterRows: number;
+  replicaRows: number;
+  /** Order-independent checksum over every column of every row. */
+  masterChecksum: string;
+  replicaChecksum: string;
+  matches: boolean;
+}
+
+export interface VerifyResult {
+  /** True only when every table matched on both count and checksum. */
+  identical: boolean;
+  tables: TableFingerprint[];
+  /** Set instead of `tables` when the comparison could not be run at all. */
+  problem: string | null;
+  checkedAt: string;
+  /** Wall-clock cost, because this is a full scan and the caller should see it. */
+  elapsedMs: number;
+}
+
+export interface ReplicationStatus {
+  /** false when the replica is not configured for this environment at all. */
+  configured: boolean;
+  /** true only when both threads run, no error is set, and lag is within bounds. */
+  healthy: boolean;
+  host: string | null;
+  ioRunning: string | null;
+  sqlRunning: string | null;
+  /** null when MySQL reports NULL, which it does whenever a thread is down. */
+  secondsBehind: number | null;
+  lastIoError: string | null;
+  lastSqlError: string | null;
+  sourceHost: string | null;
+  /** Relay-log apply progress. Null when the status output has no positions. */
+  apply: ApplyProgress | null;
+  /** GTID comparison against the master. Null when the master was unreachable. */
+  drift: GtidDrift | null;
+  /** Human-readable reason when healthy is false. */
+  problem: string | null;
+  checkedAt: string;
+}
+
+/**
+ * The tables `my.jorgecuadros.com` reads through the `web_reader` grant.
+ *
+ * This list is the verification surface, not the replication surface — the
+ * replica carries the whole schema. These are the eight whose divergence would
+ * actually be visible to a customer, so they are the ones worth a full scan.
+ */
+export const REPLICATED_TABLES = [
+  "transactions",
+  "customers",
+  "customer_legacy_refs",
+  "type_transactions",
+  "exchange_rates",
+  "properties",
+  "property_services",
+  "trust_accounts",
+] as const;
+
+/**
+ * Reports whether the my.jorgecuadros.com read replica is still replicating.
+ *
+ * The replica is what the public site reads once the platformDataSource flag is
+ * on, and a replica that has silently stopped applying serves stale balances
+ * rather than erroring — the failure is invisible from the site itself, which is
+ * why it needs a panel.
+ *
+ * Shells out to the mysql client for the same reason the rest of OpsService
+ * does: there is no MySQL driver in this API's dependencies, and the image
+ * already ships one.
+ */
+@Injectable()
+export class ReplicationService {
+  private readonly logger = new Logger(ReplicationService.name);
+
+  /** Lag above this many seconds is reported as unhealthy. */
+  private readonly maxLagSeconds = Number(process.env.REPLICA_MAX_LAG ?? 60);
+
+  async status(): Promise<ReplicationStatus> {
+    const host = process.env.REPLICA_DB_HOST;
+    const user = process.env.REPLICA_DB_USER;
+    const password = process.env.REPLICA_DB_PASS;
+    const now = new Date().toISOString();
+
+    const empty: ReplicationStatus = {
+      configured: false,
+      healthy: false,
+      host: host ?? null,
+      ioRunning: null,
+      sqlRunning: null,
+      secondsBehind: null,
+      lastIoError: null,
+      lastSqlError: null,
+      sourceHost: null,
+      apply: null,
+      drift: null,
+      problem: null,
+      checkedAt: now,
+    };
+
+    if (!host || !user || !password) {
+      return { ...empty, problem: "REPLICA_DB_* no configuradas" };
+    }
+
+    let raw: string;
+    try {
+      raw = await this.onReplica("SHOW REPLICA STATUS\\G");
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      this.logger.warn(`no se pudo consultar la réplica: ${msg}`);
+      return { ...empty, configured: true, problem: `No se pudo conectar: ${msg}` };
+    }
+
+    const field = (name: string): string | null => replicaField(raw, name);
+
+    // An empty result set means the server is not configured as a replica at
+    // all — distinct from "configured but broken", and worth saying plainly.
+    if (!raw.includes("Replica_IO_Running")) {
+      return {
+        ...empty,
+        configured: true,
+        problem: "El servidor no está configurado como réplica",
+      };
+    }
+
+    const ioRunning = field("Replica_IO_Running");
+    const sqlRunning = field("Replica_SQL_Running");
+    const lagRaw = field("Seconds_Behind_Source");
+    const secondsBehind =
+      lagRaw === null || lagRaw === "NULL" ? null : Number(lagRaw);
+    const lastIoError = field("Last_IO_Error");
+    const lastSqlError = field("Last_SQL_Error");
+
+    // Order matters: report the most specific cause first. Checking lag before
+    // the threads would blame "sin dato de retraso" for what is really a
+    // stopped thread, because MySQL reports NULL lag whenever either is down.
+    let problem: string | null = null;
+    if (ioRunning !== "Yes") problem = "El hilo de E/S no está corriendo";
+    else if (sqlRunning !== "Yes") problem = "El hilo SQL no está corriendo";
+    else if (lastSqlError) problem = `Error SQL: ${lastSqlError}`;
+    else if (lastIoError) problem = `Error de E/S: ${lastIoError}`;
+    else if (secondsBehind === null) problem = "Sin dato de retraso";
+    else if (secondsBehind > this.maxLagSeconds)
+      problem = `Retraso de ${secondsBehind}s (máximo ${this.maxLagSeconds}s)`;
+
+    return {
+      configured: true,
+      healthy: problem === null,
+      host,
+      ioRunning,
+      sqlRunning,
+      secondsBehind,
+      lastIoError,
+      lastSqlError,
+      sourceHost: field("Source_Host"),
+      // Reported, never folded into `healthy`: a non-zero backlog is the normal
+      // state of a working replica for the instant between fetch and apply, so
+      // alarming on it would cry wolf. It is here to answer "is it moving?"
+      // when the lag counter is stuck.
+      apply: applyProgress(raw),
+      // Also reported rather than alarmed on, for the same reason: a busy master
+      // is always a few transactions ahead for the instant they are in flight.
+      // Null rather than zero when the master could not be reached — "unknown"
+      // and "identical" must not render the same.
+      drift: await this.gtidDrift(),
+      problem,
+      checkedAt: now,
+    };
+  }
+
+  /**
+   * Compare executed history between master and replica.
+   *
+   * Two round trips: ask the master what it has executed, then ask the replica
+   * to subtract its own history from that. The subtraction runs on the replica
+   * rather than in TypeScript because `GTID_SUBTRACT` already implements the
+   * interval algebra correctly, and reimplementing set subtraction over binlog
+   * ranges is exactly the kind of thing that looks right and is wrong at the
+   * boundaries.
+   *
+   * @returns null on any failure — a broken drift check must never be mistaken
+   *          for a healthy zero.
+   */
+  private async gtidDrift(): Promise<GtidDrift | null> {
+    try {
+      const masterGtid = (await this.onMaster("SELECT @@gtid_executed")).trim();
+
+      // GTID sets are UUIDs, digits, colons, commas, hyphens, whitespace and
+      // (since 8.4) alphanumeric tags. Nothing else is legal, so rejecting
+      // anything outside that alphabet is a whitelist, not a blacklist: with no
+      // quote and no backslash able to survive it, the value cannot escape the
+      // string literal it is interpolated into below.
+      if (masterGtid && !/^[0-9a-fA-F:,\s_-]+$/.test(masterGtid)) {
+        this.logger.warn("gtid_executed del maestro con formato inesperado");
+        return null;
+      }
+      // An empty set means the master has GTID mode off, and there is nothing
+      // meaningful to compare.
+      if (!masterGtid) return null;
+
+      const flat = masterGtid.replace(/\s+/g, "");
+      // Every GTID set is flattened with REPLACE before it leaves the server.
+      // MySQL wraps `gtid_executed` across lines once it holds more than one
+      // source UUID, and this is read back as tab-separated columns — an
+      // embedded newline would split one row into two and silently truncate the
+      // set at the first UUID.
+      const out = await this.onReplica(
+        "SELECT REPLACE(GTID_SUBTRACT(" +
+          `'${flat}', @@gtid_executed), '\\n', ''), ` +
+          "@@server_uuid, REPLACE(@@gtid_executed, '\\n', '')",
+        ["-N"],
+      );
+
+      // Trailing newline only — never `.trim()`. When nothing is missing the
+      // first column is the empty string, so the line begins with a tab, and
+      // trimming it would shift every column one position left and report the
+      // replica's own UUID as the missing GTID set.
+      const [missingSet = "", serverUuid = "", executed = ""] = out
+        .replace(/\r?\n+$/, "")
+        .split("\t");
+
+      return {
+        missingTransactions: countGtids(missingSet),
+        missingGtidSet: missingSet || null,
+        localTransactions: countGtids(gtidsForUuid(executed, serverUuid)),
+      };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      this.logger.warn(`no se pudo comparar GTIDs con el maestro: ${msg}`);
+      return null;
+    }
+  }
+
+  /**
+   * Full-scan comparison of the customer-visible tables on both sides.
+   *
+   * Deliberately NOT part of `status()`: this reads every row of every table in
+   * `REPLICATED_TABLES` on both servers, so it belongs behind a button, not a
+   * 30-second poll.
+   *
+   * It answers the one question GTID drift cannot. GTIDs prove the replica
+   * applied every transaction the master produced; they say nothing about rows
+   * changed on the replica by some other route. A local write is invisible to
+   * every other field on the card and shows up here as a checksum mismatch.
+   */
+  async verify(): Promise<VerifyResult> {
+    const started = Date.now();
+    const base: VerifyResult = {
+      identical: false,
+      tables: [],
+      problem: null,
+      checkedAt: new Date().toISOString(),
+      elapsedMs: 0,
+    };
+
+    let sql: string;
+    try {
+      sql = await this.fingerprintSql();
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { ...base, problem: `No se pudo leer el esquema: ${msg}`, elapsedMs: Date.now() - started };
+    }
+
+    let masterOut: string;
+    let replicaOut: string;
+    try {
+      // Sequential, not parallel. Running both at once would have the master
+      // scan under the replica's own read load only sometimes, which makes a
+      // slow run hard to attribute; and the boxes are small enough that two
+      // concurrent full scans is a real memory event on the 946MB replica.
+      masterOut = await this.onMaster(sql);
+      replicaOut = await this.onReplica(sql);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { ...base, problem: `No se pudo comparar: ${msg}`, elapsedMs: Date.now() - started };
+    }
+
+    const master = parseFingerprints(masterOut);
+    const replica = parseFingerprints(replicaOut);
+
+    const tables: TableFingerprint[] = REPLICATED_TABLES.map((table) => {
+      const m = master.get(table);
+      const r = replica.get(table);
+      return {
+        table,
+        masterRows: m?.rows ?? -1,
+        replicaRows: r?.rows ?? -1,
+        masterChecksum: m?.checksum ?? "?",
+        replicaChecksum: r?.checksum ?? "?",
+        // Both sides must have answered. A missing row on either side is a
+        // mismatch, never a pass — `undefined === undefined` would otherwise
+        // report two failed reads as agreement.
+        matches:
+          m !== undefined && r !== undefined && m.rows === r.rows && m.checksum === r.checksum,
+      };
+    });
+
+    return {
+      identical: tables.every((t) => t.matches),
+      tables,
+      problem: null,
+      checkedAt: base.checkedAt,
+      elapsedMs: Date.now() - started,
+    };
+  }
+
+  /**
+   * Build the count+checksum query from the live column list.
+   *
+   * The columns come from `information_schema` on the master rather than being
+   * hardcoded, so the check keeps covering the whole row after a migration adds
+   * one. Reading the schema from the master is safe by construction: if the two
+   * schemas had diverged, replication would already be broken.
+   */
+  private async fingerprintSql(): Promise<string> {
+    const list = REPLICATED_TABLES.map((t) => `'${t}'`).join(",");
+    const raw = await this.onMaster(
+      "SELECT CONCAT(TABLE_NAME, '\\t', COLUMN_NAME) FROM information_schema.COLUMNS " +
+        `WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (${list}) ` +
+        "ORDER BY TABLE_NAME, ORDINAL_POSITION",
+      ["-N"],
+    );
+
+    const cols = new Map<string, string[]>();
+    for (const line of raw.split("\n")) {
+      const [table, column] = line.trim().split("\t");
+      if (!table || !column) continue;
+      cols.set(table, [...(cols.get(table) ?? []), column]);
+    }
+
+    const selects = REPLICATED_TABLES.map((table) => {
+      const columns = cols.get(table);
+      if (!columns?.length) throw new Error(`tabla ${table} sin columnas`);
+      // CONVERT(... USING binary), never CAST(... AS CHAR).
+      //
+      // CAST to CHAR transcodes into the *connection* character set, which is
+      // not the same on the two servers: the mysql client inside the master's
+      // container negotiates latin1, while the replica's negotiates utf8mb4.
+      // Every accented character in a Mexican name, street or note therefore
+      // hashes to different bytes on each side, and the comparison reports a
+      // permanent mismatch on exactly the tables that hold free text — a
+      // verification tool that always cries wolf, which is worse than none.
+      // Comparing the stored bytes sidesteps the session entirely. (Verified
+      // 2026-08-06: with CAST, `customers.name` gave 3344437324815 vs
+      // 3339150372121; with CONVERT both give 3339150372121.)
+      //
+      // 0x1f (unit separator) joins the columns and 0x1e (record separator)
+      // stands in for NULL. Both matter: CONCAT_WS *skips* NULLs rather than
+      // emitting an empty field, so without a placeholder the rows
+      // ('a', NULL, 'b') and ('a', 'b', NULL) produce the same string and a
+      // column-shifting bug would checksum as identical.
+      const expr = columns
+        .map((c) => `IFNULL(CONVERT(\`${c}\` USING binary), 0x1e)`)
+        .join(", 0x1f, ");
+      // SUM, not a running hash: addition is commutative, so the result does not
+      // depend on the order rows come back in. The two servers have no reason to
+      // scan in the same order and are not asked to.
+      return (
+        `SELECT '${table}' AS t, COUNT(*) AS n, ` +
+        `IFNULL(SUM(CRC32(CONCAT_WS(0x1f, ${expr}))), 0) AS c FROM \`${table}\``
+      );
+    });
+
+    return selects.join(" UNION ALL ");
+  }
+
+  /* ------------------------------------------------------------ plumbing */
+
+  /**
+   * Run a statement on the replica.
+   *
+   * --ssl is required: the replica sets require_secure_transport=ON.
+   *
+   * --ssl-verify-server-cert=0 is deliberate and is NOT the same trade-off the
+   * website makes. This hop never leaves Tailscale — the replica is reached on
+   * its CGNAT tailnet address and the tailnet ACL admits only this host — so
+   * WireGuard already authenticates the peer. The DreamHost leg crosses the
+   * public internet and therefore pins the CA instead. The client here is
+   * MariaDB's, which rejects our self-signed CA outright unless it is handed the
+   * CA file, which would mean shipping a cert into this image for a link that is
+   * already authenticated.
+   */
+  private async onReplica(sql: string, extra: string[] = []): Promise<string> {
+    const host = process.env.REPLICA_DB_HOST!;
+    const user = process.env.REPLICA_DB_USER!;
+    const password = process.env.REPLICA_DB_PASS!;
+    const { stdout } = await exec(
+      "mysql",
+      [
+        `--host=${host}`,
+        `--user=${user}`,
+        "--ssl",
+        "--ssl-verify-server-cert=0",
+        "--connect-timeout=5",
+        ...extra,
+        "-e",
+        sql,
+      ],
+      { env: { ...process.env, MYSQL_PWD: password }, timeout: VERIFY_TIMEOUT_MS },
+    );
+    return stdout;
+  }
+
+  /**
+   * Run a statement on the master, using the application's own DATABASE_URL.
+   *
+   * The app credential is enough here on purpose — everything this class sends
+   * to the master is a SELECT against `information_schema` or a system variable.
+   * Reaching for OPS_DB_ADMIN_* the way OpsService does would hand a monitoring
+   * read path a credential that can also restore a dump.
+   */
+  private async onMaster(sql: string, extra: string[] = []): Promise<string> {
+    const raw = process.env.DATABASE_URL;
+    if (!raw) throw new Error("DATABASE_URL no está configurada");
+    const u = new URL(raw);
+    const { stdout } = await exec(
+      "mysql",
+      [
+        `--host=${u.hostname}`,
+        `--port=${u.port || "3306"}`,
+        `--user=${decodeURIComponent(u.username)}`,
+        "--connect-timeout=5",
+        ...extra,
+        "-N",
+        "-e",
+        sql,
+        u.pathname.replace(/^\//, ""),
+      ],
+      {
+        env: { ...process.env, MYSQL_PWD: decodeURIComponent(u.password) },
+        timeout: VERIFY_TIMEOUT_MS,
+      },
+    );
+    return stdout;
+  }
+}
+
+/** Full scans on a 1-vCPU replica are not fast; 15s would cut them off. */
+const VERIFY_TIMEOUT_MS = 120_000;
+
+/** Parse the `t\tn\tc` rows the fingerprint query emits under `mysql -N`. */
+function parseFingerprints(raw: string): Map<string, { rows: number; checksum: string }> {
+  const out = new Map<string, { rows: number; checksum: string }>();
+  for (const line of raw.split("\n")) {
+    const [table, n, c] = line.trim().split("\t");
+    if (!table || n === undefined || c === undefined) continue;
+    const rows = Number(n);
+    if (!Number.isFinite(rows)) continue;
+    // The checksum stays a string. Sums of CRC32 over 40k rows exceed 2^53, so
+    // parsing it as a number would round and make distinct tables compare equal.
+    out.set(table, { rows, checksum: c });
+  }
+  return out;
+}
+
+/**
+ * Count the transactions in a GTID set.
+ *
+ * Exported for testing. The format is `uuid[:tag]:interval[:interval]...`,
+ * comma-separated, where an interval is `N` or `N-M` inclusive at both ends —
+ * so `1-5` is five transactions, not four.
+ *
+ * MySQL 8.4 added an optional alphanumeric tag between the UUID and the first
+ * interval. It is skipped rather than parsed: any segment that is not a number
+ * or a number range is not an interval, whatever else it may be.
+ */
+export function countGtids(set: string): number {
+  if (!set.trim()) return 0;
+  let total = 0;
+  for (const group of set.split(",")) {
+    for (const part of group.trim().split(":").slice(1)) {
+      const m = /^(\d+)(?:-(\d+))?$/.exec(part.trim());
+      if (!m) continue;
+      const from = Number(m[1]);
+      const to = m[2] === undefined ? from : Number(m[2]);
+      if (Number.isFinite(from) && Number.isFinite(to) && to >= from) total += to - from + 1;
+    }
+  }
+  return total;
+}
+
+/**
+ * Narrow a GTID set to the intervals belonging to one server UUID.
+ *
+ * Exported for testing. Used to isolate the replica's own writes from the
+ * history it replicated, which are interleaved in the same `gtid_executed`.
+ */
+export function gtidsForUuid(set: string, uuid: string): string {
+  if (!uuid.trim()) return "";
+  const wanted = uuid.trim().toLowerCase();
+  return set
+    .split(",")
+    .map((g) => g.trim())
+    .filter((g) => g.toLowerCase().startsWith(`${wanted}:`))
+    .join(",");
+}
+
+/**
+ * Derive relay-apply progress from `SHOW REPLICA STATUS\G` output.
+ *
+ * Exported for testing. Free in query terms — it re-reads four more fields from
+ * the output the caller already has, with no second round trip to the replica
+ * and no connection to the source.
+ *
+ * @returns null when either position is missing or unparseable, which is what
+ *          happens on a server that is not a replica at all.
+ */
+export function applyProgress(raw: string): ApplyProgress | null {
+  const num = (name: string): number | null => {
+    const v = replicaField(raw, name);
+    if (v === null || v === "NULL") return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  };
+
+  const readPos = num("Read_Source_Log_Pos");
+  const execPos = num("Exec_Source_Log_Pos");
+  if (readPos === null || execPos === null) return null;
+
+  const sourceLogFile = replicaField(raw, "Source_Log_File");
+  const relayLogFile = replicaField(raw, "Relay_Source_Log_File");
+  const sameFile =
+    sourceLogFile !== null && relayLogFile !== null && sourceLogFile === relayLogFile;
+
+  // Clamped at 0: the SQL thread cannot be ahead of the I/O thread, but the two
+  // fields are sampled independently, so a rotation racing this read can print
+  // a momentarily negative delta. Zero is the honest floor, not a bug.
+  const backlogBytes = sameFile ? Math.max(0, readPos - execPos) : null;
+
+  let percent: number | null = null;
+  if (backlogBytes !== null && readPos > 0) {
+    // Truncate rather than round, and hold short of 100 while bytes remain —
+    // see the doc on ApplyProgress.percent.
+    const p = Math.floor((execPos / readPos) * 10_000) / 100;
+    percent = backlogBytes === 0 ? 100 : Math.min(p, 99.99);
+  }
+
+  return { sourceLogFile, readPos, relayLogFile, execPos, sameFile, backlogBytes, percent };
+}
+
+/**
+ * Read one field out of `SHOW REPLICA STATUS\G` output.
+ *
+ * Exported for testing, and worth testing: the obvious regex is wrong.
+ * `\s` matches newlines in JavaScript, so `^\s*NAME:\s*(.*)$` lets the `\s*`
+ * after the colon swallow the line break of an EMPTY field and capture the
+ * following line instead. Last_SQL_Error is empty on a healthy replica, so that
+ * version reported the next line ("Replicate_Ignore_Server_Ids:") as a SQL
+ * error and rendered a perfectly healthy replica as broken.
+ *
+ * Hence `[^\S\n]` — horizontal whitespace only — on both sides of the name.
+ *
+ * @returns the trimmed value, or null when the field is absent OR empty. Empty
+ *          and absent mean the same thing to every caller here: MySQL prints
+ *          error fields as blank rather than omitting them.
+ */
+export function replicaField(raw: string, name: string): string | null {
+  const m = raw.match(new RegExp(`^[^\\S\\n]*${name}:[^\\S\\n]*(.*)$`, "m"));
+  const v = m?.[1]?.trim();
+  return v === undefined || v === "" ? null : v;
+}

apps/api/src/ops/replication.spec.ts

@@ -0,0 +1,254 @@
+import {
+  applyProgress,
+  countGtids,
+  gtidsForUuid,
+  replicaField,
+} from "./replication.service";
+
+/**
+ * Verbatim shape of `SHOW REPLICA STATUS\G` from the live replica, trimmed to
+ * the fields the panel reads plus the neighbours that matter.
+ *
+ * The empty `Last_SQL_Error:` immediately followed by
+ * `Replicate_Ignore_Server_Ids:` is the whole point of the fixture — that exact
+ * adjacency is what the first implementation misread.
+ */
+const HEALTHY = [
+  "*************************** 1. row ***************************",
+  "             Replica_IO_State: Waiting for source to send event",
+  "                  Source_Host: 100.103.77.46",
+  "                  Source_User: repl",
+  "              Source_Log_File: binlog.000042",
+  "          Read_Source_Log_Pos: 194884231",
+  "        Relay_Source_Log_File: binlog.000042",
+  "          Exec_Source_Log_Pos: 194884231",
+  "           Replica_IO_Running: Yes",
+  "          Replica_SQL_Running: Yes",
+  "              Replicate_Do_DB: ",
+  "                   Last_Errno: 0",
+  "                   Last_Error: ",
+  "        Seconds_Behind_Source: 0",
+  "                Last_IO_Errno: 0",
+  "                Last_IO_Error: ",
+  "               Last_SQL_Errno: 0",
+  "               Last_SQL_Error: ",
+  "  Replicate_Ignore_Server_Ids: ",
+  "             Source_Server_Id: 1",
+].join("\n");
+
+const BROKEN = [
+  "           Replica_IO_Running: Yes",
+  "          Replica_SQL_Running: No",
+  "        Seconds_Behind_Source: NULL",
+  "                Last_IO_Error: ",
+  "               Last_SQL_Error: Could not execute Write_rows event on table jorgecuadros.customers",
+  "  Replicate_Ignore_Server_Ids: ",
+].join("\n");
+
+describe("replicaField", () => {
+  it("reads plain values", () => {
+    expect(replicaField(HEALTHY, "Replica_IO_Running")).toBe("Yes");
+    expect(replicaField(HEALTHY, "Replica_SQL_Running")).toBe("Yes");
+    expect(replicaField(HEALTHY, "Source_Host")).toBe("100.103.77.46");
+    expect(replicaField(HEALTHY, "Seconds_Behind_Source")).toBe("0");
+  });
+
+  /**
+   * The regression this file exists for. `\s` matches newlines in JavaScript,
+   * so `^\s*NAME:\s*(.*)$` walks past an empty field's line break and captures
+   * the NEXT line — turning a healthy replica into
+   * "Error SQL: Replicate_Ignore_Server_Ids:" in the admin panel.
+   */
+  it("returns null for an empty field instead of the following line", () => {
+    expect(replicaField(HEALTHY, "Last_SQL_Error")).toBeNull();
+    expect(replicaField(HEALTHY, "Last_IO_Error")).toBeNull();
+    expect(replicaField(HEALTHY, "Last_Error")).toBeNull();
+    expect(replicaField(HEALTHY, "Replicate_Do_DB")).toBeNull();
+    expect(replicaField(HEALTHY, "Replicate_Ignore_Server_Ids")).toBeNull();
+  });
+
+  it("still reads a real error when there is one", () => {
+    expect(replicaField(BROKEN, "Last_SQL_Error")).toBe(
+      "Could not execute Write_rows event on table jorgecuadros.customers",
+    );
+    expect(replicaField(BROKEN, "Replica_SQL_Running")).toBe("No");
+  });
+
+  /** NULL is a distinct state from empty and must survive as the literal. */
+  it("preserves the literal NULL that MySQL prints for unknown lag", () => {
+    expect(replicaField(BROKEN, "Seconds_Behind_Source")).toBe("NULL");
+  });
+
+  it("returns null for a field that is not present at all", () => {
+    expect(replicaField(HEALTHY, "Nonexistent_Field")).toBeNull();
+  });
+
+  /**
+   * Field names are matched at the start of a line. Without the line anchor,
+   * "Last_Error" would also match inside "Last_SQL_Error" and read the wrong
+   * value — the two carry different things and both feed the panel.
+   */
+  it("does not match a field name that is a suffix of another", () => {
+    const raw = "               Last_SQL_Error: boom\n                   Last_Error: ";
+    expect(replicaField(raw, "Last_Error")).toBeNull();
+    expect(replicaField(raw, "Last_SQL_Error")).toBe("boom");
+  });
+});
+
+/** Builds the four position fields the apply-progress reader cares about. */
+function positions(
+  sourceFile: string,
+  readPos: number | string,
+  relayFile: string,
+  execPos: number | string,
+): string {
+  return [
+    `              Source_Log_File: ${sourceFile}`,
+    `          Read_Source_Log_Pos: ${readPos}`,
+    `        Relay_Source_Log_File: ${relayFile}`,
+    `          Exec_Source_Log_Pos: ${execPos}`,
+  ].join("\n");
+}
+
+describe("applyProgress", () => {
+  it("reports zero backlog and 100% when both positions match", () => {
+    const p = applyProgress(HEALTHY)!;
+    expect(p.sameFile).toBe(true);
+    expect(p.sourceLogFile).toBe("binlog.000042");
+    expect(p.readPos).toBe(194884231);
+    expect(p.execPos).toBe(194884231);
+    expect(p.backlogBytes).toBe(0);
+    expect(p.percent).toBe(100);
+  });
+
+  it("reports the byte delta when the SQL thread trails inside one file", () => {
+    const p = applyProgress(positions("binlog.000042", 2_000_000, "binlog.000042", 1_500_000))!;
+    expect(p.backlogBytes).toBe(500_000);
+    expect(p.percent).toBe(75);
+  });
+
+  /**
+   * The reason the byte delta exists at all. `Seconds_Behind_Source` holds at 0
+   * while the SQL thread is mid-transaction, so the backlog is the only field
+   * that moves — and the only one that says the replica is not caught up.
+   */
+  it("shows a backlog even when the lag counter reads zero", () => {
+    const raw = [
+      "        Seconds_Behind_Source: 0",
+      positions("binlog.000042", 900, "binlog.000042", 400),
+    ].join("\n");
+    expect(replicaField(raw, "Seconds_Behind_Source")).toBe("0");
+    expect(applyProgress(raw)!.backlogBytes).toBe(500);
+  });
+
+  /**
+   * Positions restart near 4 in every new binlog file, so subtracting across
+   * files produces a number that is not a backlog — here it would be a large
+   * NEGATIVE one, which would render as "ahead of the source".
+   */
+  it("refuses to compare positions across different binlog files", () => {
+    const p = applyProgress(positions("binlog.000043", 500, "binlog.000042", 194_000_000))!;
+    expect(p.sameFile).toBe(false);
+    expect(p.backlogBytes).toBeNull();
+    expect(p.percent).toBeNull();
+    expect(p.sourceLogFile).toBe("binlog.000043");
+    expect(p.relayLogFile).toBe("binlog.000042");
+  });
+
+  /**
+   * Percent must not round up to 100 while bytes remain: binlog positions are
+   * large, so a genuine backlog is a rounding error away from the whole file
+   * and would otherwise render as "caught up" on a replica that is not.
+   */
+  it("stops short of 100% while any backlog remains", () => {
+    const p = applyProgress(positions("binlog.000042", 194_884_231, "binlog.000042", 194_884_230))!;
+    expect(p.backlogBytes).toBe(1);
+    expect(p.percent).toBe(99.99);
+  });
+
+  /** Sampled independently, so a rotation racing the read can invert them. */
+  it("clamps a momentarily negative delta to zero", () => {
+    const p = applyProgress(positions("binlog.000042", 400, "binlog.000042", 500))!;
+    expect(p.backlogBytes).toBe(0);
+    expect(p.percent).toBe(100);
+  });
+
+  it("returns null when the server is not a replica and prints no positions", () => {
+    expect(applyProgress("")).toBeNull();
+    expect(applyProgress(BROKEN)).toBeNull();
+  });
+
+  /** A stopped thread makes MySQL print NULL, which is not a position. */
+  it("returns null when a position is NULL", () => {
+    expect(applyProgress(positions("binlog.000042", "NULL", "binlog.000042", 400))).toBeNull();
+  });
+});
+
+/**
+ * Real GTID sets from the live pair, captured 2026-08-06. The replica's own
+ * server UUID (3b103283…) carries the transactions the seed dump load executed
+ * locally; the master's UUID (defc34e2…) carries the replicated history.
+ */
+const REPLICA_EXECUTED =
+  "3b103283-8f15-11f1-a52b-020017027b33:1-513," +
+  "defc34e2-8c5d-11f1-8e58-52c4c853bce8:1-525";
+const REPLICA_UUID = "3b103283-8f15-11f1-a52b-020017027b33";
+
+describe("countGtids", () => {
+  it("counts an inclusive range at both ends", () => {
+    // 1-5 is five transactions. Off-by-one here understates the gap, which is
+    // the direction that hides a problem.
+    expect(countGtids("defc34e2-8c5d-11f1-8e58-52c4c853bce8:1-5")).toBe(5);
+  });
+
+  it("counts a bare single transaction", () => {
+    expect(countGtids("defc34e2-8c5d-11f1-8e58-52c4c853bce8:7")).toBe(1);
+  });
+
+  it("sums several intervals under one UUID", () => {
+    expect(countGtids("defc34e2-8c5d-11f1-8e58-52c4c853bce8:1-5:8:10-12")).toBe(9);
+  });
+
+  it("sums across UUIDs, including the wrapped form MySQL prints", () => {
+    expect(countGtids(REPLICA_EXECUTED)).toBe(513 + 525);
+    // `gtid_executed` comes back wrapped once it holds more than one UUID.
+    expect(countGtids(REPLICA_EXECUTED.replace(",", ",\n"))).toBe(513 + 525);
+  });
+
+  /** An empty subtraction result is the caught-up case and must be zero. */
+  it("returns 0 for an empty or blank set", () => {
+    expect(countGtids("")).toBe(0);
+    expect(countGtids("   \n ")).toBe(0);
+  });
+
+  /**
+   * MySQL 8.4 allows an alphanumeric tag between the UUID and the intervals.
+   * It is not an interval and must not be counted as one.
+   */
+  it("skips a tag without counting it", () => {
+    expect(countGtids("defc34e2-8c5d-11f1-8e58-52c4c853bce8:mytag:1-3")).toBe(3);
+  });
+});
+
+describe("gtidsForUuid", () => {
+  it("isolates the replica's own transactions from the replicated history", () => {
+    expect(countGtids(gtidsForUuid(REPLICA_EXECUTED, REPLICA_UUID))).toBe(513);
+  });
+
+  it("returns nothing for a UUID that is not in the set", () => {
+    expect(gtidsForUuid(REPLICA_EXECUTED, "00000000-0000-0000-0000-000000000000")).toBe("");
+  });
+
+  /**
+   * The colon matters. Without it a UUID prefix would match a longer UUID that
+   * merely starts the same way, and the replica's local writes would be
+   * over-reported.
+   */
+  it("does not match on a bare prefix", () => {
+    expect(gtidsForUuid(REPLICA_EXECUTED, "3b103283")).toBe("");
+  });
+
+  it("returns nothing when the UUID is blank", () => {
+    expect(gtidsForUuid(REPLICA_EXECUTED, "")).toBe("");
+  });
+});

apps/api/src/ops/start-job.dto.ts

@@ -1,4 +1,4 @@
-import { IsEnum, IsOptional, IsString } from "class-validator";
+import { IsBoolean, IsEnum, IsOptional, IsString } from "class-validator";
 import { OpsJobKind } from "@jorgecuadros/database";
 
 export class StartJobDto {
@@ -9,4 +9,13 @@ export class StartJobDto {
   @IsOptional()
   @IsString()
   file?: string;
+
+  /**
+   * REIMPORT only: proceed even though the rebuild deletes rows that exist only
+   * in the platform. Off by default, so the guard in run_all.py stops the job
+   * and lists what would be lost rather than the operator finding out after.
+   */
+  @IsOptional()
+  @IsBoolean()
+  forceFull?: boolean;
 }

apps/api/src/policies/children.dto.ts

@@ -12,6 +12,10 @@ import { Currency } from "@jorgecuadros/database";
 // Each child DTO covers create; updates reuse the same shape with all fields
 // optional via the corresponding Update class. Route supplies the policyId.
 
+// A policy split into several exhibiciones prices each payment on its own —
+// the Access form printed the whole money row once per pago — so the premium
+// breakdown repeats here. `amount` remains what was actually collected and is
+// never recomputed from the breakdown; the two differ by rounding in the books.
 export class InstallmentDto {
   @IsInt() sequence!: number;
   @IsOptional() @IsNumber() amount?: number;
@@ -20,6 +24,13 @@ export class InstallmentDto {
   @IsOptional() @IsString() paidDate?: string;
   @IsOptional() @IsString() checkNumber?: string;
   @IsOptional() @IsBoolean() isCash?: boolean;
+  @IsOptional() @IsNumber() netPremium?: number;
+  @IsOptional() @IsNumber() surcharge?: number;
+  @IsOptional() @IsNumber() policyFee?: number;
+  @IsOptional() @IsNumber() tax?: number;
+  @IsOptional() @IsNumber() taxRate?: number;
+  @IsOptional() @IsNumber() total?: number;
+  @IsOptional() @IsNumber() commission?: number;
 }
 export class UpdateInstallmentDto {
   @IsOptional() @IsInt() sequence?: number;
@@ -29,6 +40,13 @@ export class UpdateInstallmentDto {
   @IsOptional() @IsString() paidDate?: string;
   @IsOptional() @IsString() checkNumber?: string;
   @IsOptional() @IsBoolean() isCash?: boolean;
+  @IsOptional() @IsNumber() netPremium?: number;
+  @IsOptional() @IsNumber() surcharge?: number;
+  @IsOptional() @IsNumber() policyFee?: number;
+  @IsOptional() @IsNumber() tax?: number;
+  @IsOptional() @IsNumber() taxRate?: number;
+  @IsOptional() @IsNumber() total?: number;
+  @IsOptional() @IsNumber() commission?: number;
 }
 
 export class VehicleDto {

apps/api/src/policies/lookup-delete-guard.spec.ts

@@ -0,0 +1,94 @@
+import { BadRequestException } from "@nestjs/common";
+import { PoliciesService } from "./policies.service";
+
+/**
+ * Deleting a lookup row that policies still reference used to succeed and
+ * silently blank the field on every one of them, because both FKs are
+ * `ON DELETE SET NULL` (`0000_init`). That is not a hypothetical: it is how
+ * the `M_EMPR` policy type disappeared from the dev database and left 5
+ * policies with a null `policyTypeId`, found only by querying months later.
+ *
+ * These tests pin the refusal. They drive the service with a stub client
+ * rather than a database because what is being asserted is the guard, not
+ * Prisma — and a test that needed a live MySQL would not run in CI.
+ */
+function serviceWith(counts: {
+  policies?: number;
+  claims?: number;
+}): { service: PoliciesService; deleted: string[] } {
+  const deleted: string[] = [];
+  const prisma = {
+    policy: { count: async () => counts.policies ?? 0 },
+    claim: { count: async () => counts.claims ?? 0 },
+    insuranceProvider: {
+      findUnique: async () => ({ id: "p1", name: "ANA SEGUROS" }),
+      delete: async () => {
+        deleted.push("provider");
+        return { id: "p1" };
+      },
+    },
+    policyType: {
+      findUnique: async () => ({ id: "t1", name: "M_EMPR" }),
+      delete: async () => {
+        deleted.push("policyType");
+        return { id: "t1" };
+      },
+    },
+    adjuster: {
+      findUnique: async () => ({ id: "a1", name: "JUAN PEREZ" }),
+      delete: async () => {
+        deleted.push("adjuster");
+        return { id: "a1" };
+      },
+    },
+  };
+  const storage = {} as never;
+  return {
+    service: new PoliciesService(prisma as never, storage),
+    deleted,
+  };
+}
+
+describe("lookup deletes refuse while the row is in use", () => {
+  it("refuses a policy type that policies still carry, and names the count", () => {
+    const { service, deleted } = serviceWith({ policies: 5 });
+    return service.removePolicyType("t1").then(
+      () => {
+        throw new Error("expected the delete to be refused");
+      },
+      (err: unknown) => {
+        expect(err).toBeInstanceOf(BadRequestException);
+        // The operator has to be told WHICH row and HOW MANY, or the message
+        // is not actionable.
+        expect((err as Error).message).toContain("M_EMPR");
+        expect((err as Error).message).toContain("5");
+        expect(deleted).toEqual([]);
+      },
+    );
+  });
+
+  it("refuses a carrier that policies still carry", async () => {
+    const { service, deleted } = serviceWith({ policies: 738 });
+    await expect(service.removeProvider("p1")).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+    expect(deleted).toEqual([]);
+  });
+
+  it("refuses an adjuster still assigned to claims", async () => {
+    // Same `ON DELETE SET NULL` trap, on `claims.adjusterId`.
+    const { service, deleted } = serviceWith({ claims: 2 });
+    await expect(service.removeAdjuster("a1")).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+    expect(deleted).toEqual([]);
+  });
+
+  it("allows the delete once nothing references the row", async () => {
+    const { service, deleted } = serviceWith({ policies: 0, claims: 0 });
+    await service.removePolicyType("t1");
+    await service.removeProvider("p1");
+    await service.removeAdjuster("a1");
+    expect(deleted).toEqual(["policyType", "provider", "adjuster"]);
+  });
+});

apps/api/src/policies/lookup.dto.ts

@@ -1,4 +1,4 @@
-import { IsOptional, IsString, MinLength } from "class-validator";
+import { IsNumber, IsOptional, IsString, Max, Min, MinLength } from "class-validator";
 
 export class ProviderDto {
   @IsString() @MinLength(1) name!: string;
@@ -7,13 +7,19 @@ export class UpdateProviderDto {
   @IsOptional() @IsString() @MinLength(1) name?: string;
 }
 
+// `taxRate` is the IVA fraction for this line of business (0.08 = 8%), the
+// legacy one-row IMPUESTOS / IMPUESTOS_AUTOS tables made editable. Bounded at
+// 1 because a rate is a fraction, not a percentage: 8 entered here would tax a
+// $600 premium $4,800, and the mistake is easy to make.
 export class PolicyTypeDto {
   @IsString() @MinLength(1) name!: string;
   @IsOptional() @IsString() shortDescription?: string;
+  @IsOptional() @IsNumber() @Min(0) @Max(1) taxRate?: number;
 }
 export class UpdatePolicyTypeDto {
   @IsOptional() @IsString() @MinLength(1) name?: string;
   @IsOptional() @IsString() shortDescription?: string;
+  @IsOptional() @IsNumber() @Min(0) @Max(1) taxRate?: number;
 }
 
 export class AdjusterDto {

apps/api/src/policies/policies.service.ts

@@ -1,4 +1,4 @@
-import { Injectable, NotFoundException } from "@nestjs/common";
+import { BadRequestException, Injectable, NotFoundException } from "@nestjs/common";
 import { randomUUID } from "node:crypto";
 import { Prisma } from "@jorgecuadros/database";
 import { PrismaService } from "../prisma/prisma.service";
@@ -250,7 +250,16 @@ export class PoliciesService {
     const [types, providers] = await this.prisma.$transaction([
       this.prisma.policyType.findMany({
         orderBy: { name: "asc" },
-        select: { id: true, name: true, _count: { select: { policies: true } } },
+        select: {
+          id: true,
+          name: true,
+          shortDescription: true,
+          // The capture form computes IVA client-side as the operator types,
+          // so the rate has to travel with the type list it already loads —
+          // an extra round-trip per keystroke is not an option.
+          taxRate: true,
+          _count: { select: { policies: true } },
+        },
       }),
       this.prisma.insuranceProvider.findMany({
         orderBy: { name: "asc" },
@@ -259,7 +268,13 @@ export class PoliciesService {
     ]);
 
     return {
-      types: types.map((t) => ({ id: t.id, name: t.name, count: t._count.policies })),
+      types: types.map((t) => ({
+        id: t.id,
+        name: t.name,
+        shortDescription: t.shortDescription,
+        taxRate: t.taxRate,
+        count: t._count.policies,
+      })),
       providers: providers.map((p) => ({
         id: p.id,
         name: p.name,
@@ -397,6 +412,13 @@ export class PoliciesService {
         paidDate: toDate(dto.paidDate) ?? undefined,
         checkNumber: dto.checkNumber,
         isCash: dto.isCash,
+        netPremium: dto.netPremium,
+        surcharge: dto.surcharge,
+        policyFee: dto.policyFee,
+        tax: dto.tax,
+        taxRate: dto.taxRate,
+        total: dto.total,
+        commission: dto.commission,
       },
     });
   }
@@ -412,6 +434,13 @@ export class PoliciesService {
         ...(dto.paidDate !== undefined && { paidDate: toDate(dto.paidDate) }),
         checkNumber: dto.checkNumber,
         isCash: dto.isCash,
+        netPremium: dto.netPremium,
+        surcharge: dto.surcharge,
+        policyFee: dto.policyFee,
+        tax: dto.tax,
+        taxRate: dto.taxRate,
+        total: dto.total,
+        commission: dto.commission,
       },
     });
   }
@@ -554,7 +583,40 @@ export class PoliciesService {
   updateProvider(id: string, dto: UpdateProviderDto) {
     return this.prisma.insuranceProvider.update({ where: { id }, data: dto });
   }
-  removeProvider(id: string) {
+  /**
+   * Deleting a lookup row that policies still point at is silent data loss.
+   *
+   * Both FKs are `ON DELETE SET NULL` (see `0000_init`), so the delete
+   * succeeds, returns 200, and blanks the field on every policy that used it
+   * — with no error and nothing in the UI to suggest anything happened. That
+   * is how the `M_EMPR` policy type disappeared and left 5 policies with a
+   * null `policyTypeId`, only found later by querying.
+   *
+   * Refusing is the whole fix. There is no "are you sure": the operator
+   * reassigns those policies first, which is work the app cannot do for them
+   * because only they know which type is correct.
+   */
+  private async assertLookupUnused(
+    kind: "provider" | "policyType",
+    id: string,
+  ): Promise<void> {
+    const where = kind === "provider" ? { insuranceProviderId: id } : { policyTypeId: id };
+    const count = await this.prisma.policy.count({ where });
+    if (count === 0) return;
+
+    const label =
+      kind === "provider"
+        ? (await this.prisma.insuranceProvider.findUnique({ where: { id } }))?.name
+        : (await this.prisma.policyType.findUnique({ where: { id } }))?.name;
+    const noun = kind === "provider" ? "La aseguradora" : "El tipo de póliza";
+    throw new BadRequestException(
+      `${noun} «${label ?? id}» está en uso por ${count} póliza(s). ` +
+        "Reasígnelas antes de eliminarlo.",
+    );
+  }
+
+  async removeProvider(id: string) {
+    await this.assertLookupUnused("provider", id);
     return this.prisma.insuranceProvider.delete({ where: { id } });
   }
 
@@ -564,7 +626,8 @@ export class PoliciesService {
   updatePolicyType(id: string, dto: UpdatePolicyTypeDto) {
     return this.prisma.policyType.update({ where: { id }, data: dto });
   }
-  removePolicyType(id: string) {
+  async removePolicyType(id: string) {
+    await this.assertLookupUnused("policyType", id);
     return this.prisma.policyType.delete({ where: { id } });
   }
 
@@ -574,7 +637,17 @@ export class PoliciesService {
   updateAdjuster(id: string, dto: UpdateAdjusterDto) {
     return this.prisma.adjuster.update({ where: { id }, data: dto });
   }
-  removeAdjuster(id: string) {
+  /** Same `ON DELETE SET NULL` trap as the two above, on `claims.adjusterId`:
+   *  deleting a busy adjuster would quietly strip them off their claims. */
+  async removeAdjuster(id: string) {
+    const count = await this.prisma.claim.count({ where: { adjusterId: id } });
+    if (count > 0) {
+      const row = await this.prisma.adjuster.findUnique({ where: { id } });
+      throw new BadRequestException(
+        `El ajustador «${row?.name ?? id}» está asignado a ${count} siniestro(s). ` +
+          "Reasígnelos antes de eliminarlo.",
+      );
+    }
     return this.prisma.adjuster.delete({ where: { id } });
   }
 }

apps/api/src/policies/policy.dto.ts

@@ -6,12 +6,16 @@ import {
   IsString,
   MinLength,
 } from "class-validator";
-import { Currency } from "@jorgecuadros/database";
+import { Currency, PaymentFrequency } from "@jorgecuadros/database";
 import { IsEnum } from "class-validator";
 
 /** Editable policy-header fields. coveragesJson (freeform legacy blob) is not
  *  exposed for editing. Dates arrive as ISO strings and are coerced by the
- *  service. `total` is legacy-dead data — the UI uses netPremium. */
+ *  service. `total` is legacy-dead data on migrated rows — list and sort code
+ *  still uses netPremium — but the capture form writes it going forward, along
+ *  with `tax`, from the arithmetic in premium.ts. Both arrive as plain numbers
+ *  rather than being recomputed server-side: the printed policy is the record
+ *  of truth and staff must be able to key its rounding verbatim. */
 export class CreatePolicyDto {
   @IsString() @MinLength(1) policyNumber!: string;
   @IsString() @MinLength(1) customerId!: string;
@@ -24,10 +28,14 @@ export class CreatePolicyDto {
   @IsOptional() @IsString() policyTo?: string;
   @IsOptional() @IsInt() coveragePeriodDays?: number;
   @IsOptional() @IsNumber() netPremium?: number;
+  @IsOptional() @IsNumber() surcharge?: number;
   @IsOptional() @IsNumber() policyFee?: number;
   @IsOptional() @IsNumber() brokerFee?: number;
   @IsOptional() @IsNumber() commission?: number;
+  @IsOptional() @IsNumber() tax?: number;
+  @IsOptional() @IsNumber() taxRate?: number;
   @IsOptional() @IsNumber() total?: number;
+  @IsOptional() @IsEnum(PaymentFrequency) paymentFrequency?: PaymentFrequency;
   @IsOptional() @IsEnum(Currency) currency?: Currency;
   @IsOptional() @IsString() observations?: string;
   @IsOptional() @IsString() notes?: string;
@@ -48,10 +56,14 @@ export class UpdatePolicyDto {
   @IsOptional() @IsString() policyTo?: string;
   @IsOptional() @IsInt() coveragePeriodDays?: number;
   @IsOptional() @IsNumber() netPremium?: number;
+  @IsOptional() @IsNumber() surcharge?: number;
   @IsOptional() @IsNumber() policyFee?: number;
   @IsOptional() @IsNumber() brokerFee?: number;
   @IsOptional() @IsNumber() commission?: number;
+  @IsOptional() @IsNumber() tax?: number;
+  @IsOptional() @IsNumber() taxRate?: number;
   @IsOptional() @IsNumber() total?: number;
+  @IsOptional() @IsEnum(PaymentFrequency) paymentFrequency?: PaymentFrequency;
   @IsOptional() @IsEnum(Currency) currency?: Currency;
   @IsOptional() @IsString() observations?: string;
   @IsOptional() @IsString() notes?: string;

apps/api/src/policies/premium.spec.ts

@@ -0,0 +1,90 @@
+import {
+  DEFAULT_TAX_RATE,
+  computeTax,
+  computeTotal,
+  resolveTaxRate,
+  surchargeApplies,
+  taxableBase,
+} from "./premium";
+
+/**
+ * The reference case is policy 7006785 (MULT, semestral, GMX, two payments) as
+ * it stands in the Access books — the screen Jorge sent. Both of its money
+ * rows are asserted, because the second one is the case that proves the
+ * surcharge belongs in the taxable base and that a zero policy fee is a real
+ * value rather than a missing one.
+ */
+describe("premium arithmetic", () => {
+  it("matches the first payment of policy 7006785", () => {
+    const parts = { netPremium: 610.86, surcharge: 8.55, policyFee: 31.0 };
+    expect(taxableBase(parts)).toBe(650.41);
+    expect(computeTax(parts, 0.08)).toBe(52.03);
+    expect(computeTotal(parts, 0.08)).toBe(702.44);
+  });
+
+  it("matches the second payment of policy 7006785", () => {
+    const parts = { netPremium: 589.71, surcharge: 8.26, policyFee: 0 };
+    expect(computeTax(parts, 0.08)).toBe(47.84);
+    expect(computeTotal(parts, 0.08)).toBe(645.81);
+  });
+
+  it("excluding the surcharge does NOT reconcile", () => {
+    // Guards the one decision in this module that is easy to get wrong: the
+    // spoken-language version of the rule ("prima neta + derecho * 8%") gives
+    // 51.35, and the printed policy says 52.03.
+    const withoutSurcharge = { netPremium: 610.86, surcharge: 0, policyFee: 31.0 };
+    expect(computeTax(withoutSurcharge, 0.08)).not.toBe(52.03);
+  });
+
+  it("treats blank and null money as zero, not NaN", () => {
+    expect(taxableBase({ netPremium: "610.86", surcharge: null, policyFee: "" })).toBe(
+      610.86,
+    );
+    expect(computeTax({ netPremium: undefined, surcharge: null, policyFee: null }, 0.08))
+      .toBe(0);
+  });
+
+  it("rounds half-up to cents", () => {
+    // 100.06 * 0.08 = 8.0048 -> 8.00; 100.13 * 0.08 = 8.0104 -> 8.01.
+    expect(computeTax({ netPremium: 100.06, surcharge: 0, policyFee: 0 }, 0.08)).toBe(8);
+    expect(computeTax({ netPremium: 100.13, surcharge: 0, policyFee: 0 }, 0.08)).toBe(8.01);
+  });
+
+  describe("surchargeApplies", () => {
+    it("is false for the two single-payment frequencies", () => {
+      expect(surchargeApplies("ANNUAL")).toBe(false);
+      expect(surchargeApplies("SINGLE")).toBe(false);
+    });
+    it("is true for every split frequency", () => {
+      expect(surchargeApplies("SEMIANNUAL")).toBe(true);
+      expect(surchargeApplies("QUARTERLY")).toBe(true);
+      expect(surchargeApplies("MONTHLY")).toBe(true);
+    });
+    it("allows it when the frequency is unknown", () => {
+      // Every migrated policy is null here — the original ETL dropped FORMA
+      // PAGO — and those rows DO carry recargo figures in the legacy data.
+      expect(surchargeApplies(null)).toBe(true);
+      expect(surchargeApplies(undefined)).toBe(true);
+    });
+  });
+
+  describe("resolveTaxRate", () => {
+    it("prefers the rate the policy was issued at", () => {
+      expect(resolveTaxRate(0.16, 0.08)).toBe(0.16);
+    });
+    it("falls back to the line of business", () => {
+      expect(resolveTaxRate(null, 0.08)).toBe(0.08);
+    });
+    it("falls back to the default when nothing is configured", () => {
+      expect(resolveTaxRate(null, null)).toBe(DEFAULT_TAX_RATE);
+      expect(resolveTaxRate(undefined, "")).toBe(DEFAULT_TAX_RATE);
+    });
+    it("accepts a zero rate as a real choice, not as absent", () => {
+      // An exempt line of business must read 0, not silently fall through to 8%.
+      expect(resolveTaxRate(null, 0)).toBe(0);
+    });
+    it("accepts Prisma's decimal strings", () => {
+      expect(resolveTaxRate(null, "0.0800")).toBe(0.08);
+    });
+  });
+});

apps/api/src/policies/premium.ts

@@ -0,0 +1,86 @@
+/**
+ * The premium arithmetic the Access capture form did in unbound calculated
+ * controls, moved somewhere it can be tested.
+ *
+ * Two figures are derived, everything else is keyed by hand:
+ *
+ *   base  = netPremium + surcharge + policyFee
+ *   tax   = round(base * rate)
+ *   total = base + tax
+ *
+ * The surcharge IS part of the taxable base. That is not an assumption — it is
+ * the only reading that reconciles the books. Policy 7006785 (MULT, semestral,
+ * two payments) prints IVA 52.03 and 47.84 against net premiums 610.86 / 589.71,
+ * surcharges 8.55 / 8.26 and policy fees 31.00 / 0.00; excluding the surcharge
+ * gives 51.35, which matches nothing on the page.
+ *
+ * The surcharge itself is NEVER derived. It is the carrier's financing charge
+ * for paying in installments, quoted per policy, so staff key it in. It only
+ * ever appears on a policy that is not paid annually or in a single exhibición
+ * — `surchargeApplies` is what the UI uses to grey the field out.
+ */
+
+/** Used when neither the policy nor its type carries a rate. Matches the
+ *  single row both legacy IMPUESTOS tables held (0.08 = 8%). */
+export const DEFAULT_TAX_RATE = 0.08;
+
+export type PaymentFrequencyValue =
+  | "ANNUAL"
+  | "SEMIANNUAL"
+  | "QUARTERLY"
+  | "MONTHLY"
+  | "SINGLE";
+
+/** Paying in more than one exhibición is what earns a surcharge. A null
+ *  frequency (every migrated row — Access's FORMA PAGO was dropped by the
+ *  original ETL) is treated as "unknown, allow it" rather than "annual":
+ *  refusing to show a figure that is sitting in the legacy data would hide it. */
+export function surchargeApplies(
+  frequency: PaymentFrequencyValue | null | undefined,
+): boolean {
+  return frequency !== "ANNUAL" && frequency !== "SINGLE";
+}
+
+function num(v: unknown): number {
+  if (v === null || v === undefined || v === "") return 0;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** Half-up to cents, the way the printed policy rounds. */
+export function round2(n: number): number {
+  return Math.round((n + Number.EPSILON) * 100) / 100;
+}
+
+export interface PremiumParts {
+  netPremium?: unknown;
+  surcharge?: unknown;
+  policyFee?: unknown;
+}
+
+export function taxableBase(p: PremiumParts): number {
+  return round2(num(p.netPremium) + num(p.surcharge) + num(p.policyFee));
+}
+
+export function computeTax(p: PremiumParts, rate: number): number {
+  return round2(taxableBase(p) * rate);
+}
+
+export function computeTotal(p: PremiumParts, rate: number): number {
+  return round2(taxableBase(p) + computeTax(p, rate));
+}
+
+/** Rate ladder: the figure stored on the policy (so an old policy keeps the
+ *  rate it was issued at even after the catalog changes), else the rate on its
+ *  line of business, else the shipped default. */
+export function resolveTaxRate(
+  policyRate: unknown,
+  policyTypeRate: unknown,
+): number {
+  for (const candidate of [policyRate, policyTypeRate]) {
+    if (candidate === null || candidate === undefined || candidate === "") continue;
+    const n = Number(candidate);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  return DEFAULT_TAX_RATE;
+}

apps/api/src/policy-ocr/name-matcher.spec.ts

@@ -0,0 +1,161 @@
+import {
+  nameTokens,
+  suggestCustomersByName,
+  suggestionNote,
+  type CustomerNameRow,
+} from "./name-matcher";
+
+/**
+ * Every row here is a real name out of the customer book (1536 rows, dev
+ * mirror of production), chosen because it is one of the shapes that breaks
+ * naive matching: surname-first ordering, a middle initial, a Spanish double
+ * surname, a joint account, a missing comma, and the `(SIN NOMBRE)`
+ * placeholder the migration left for customers whose DATGRAL row had no name.
+ */
+const BOOK: CustomerNameRow[] = [
+  { id: "c1", name: "WAGONER, PAMELA" },
+  { id: "c2", name: "MCWILLIAMS, BRIAN MICHAEL" },
+  { id: "c3", name: "MCWILLIAMS, BRIAN" },
+  { id: "c4", name: "WEAKLAND, RICHARD E." },
+  { id: "c5", name: "ESTRADA, JERRY & MARILYN" },
+  { id: "c6", name: "CABALLERO PRIETO, GUILLERMO" },
+  { id: "c7", name: "GREENE STEPHANIE" },
+  { id: "c8", name: "(SIN NOMBRE)" },
+  { id: "c9", name: "MUÑOZ, LUIS ALBERTO" },
+  { id: "c10", name: "SMITH, DANIEL" },
+  { id: "c11", name: "SMITH, JOHN" },
+];
+
+describe("nameTokens", () => {
+  it("makes the two orderings the same set", () => {
+    expect(nameTokens("PAMELA WAGONER").sort()).toEqual(
+      nameTokens("WAGONER, PAMELA").sort(),
+    );
+  });
+
+  it("drops initials, particles and corporate suffixes", () => {
+    expect(nameTokens("WEAKLAND, RICHARD E.")).toEqual(["WEAKLAND", "RICHARD"]);
+    expect(nameTokens("GARCIA DE LA TORRE, ANA")).toEqual(["GARCIA", "TORRE", "ANA"]);
+    expect(nameTokens("CONSTRUCTORA BAJA S.A. DE C.V.")).toEqual([
+      "CONSTRUCTORA",
+      "BAJA",
+    ]);
+  });
+
+  it("folds accents so OCR's MUNOZ reaches the book's MUÑOZ", () => {
+    expect(nameTokens("MUÑOZ")).toEqual(["MUNOZ"]);
+  });
+
+  it("drops the phone number ANA prints against the insured name", () => {
+    // Observed verbatim from the ANA automobile face.
+    expect(nameTokens("MARIA GARCIA Ph.3102001538")).toEqual([
+      "MARIA",
+      "GARCIA",
+      "PH",
+    ]);
+  });
+});
+
+describe("suggestCustomersByName", () => {
+  it("matches the reversed name exactly", () => {
+    const [top] = suggestCustomersByName("PAMELA WAGONER", BOOK);
+    expect(top).toMatchObject({ customerId: "c1", tier: "EXACT", score: 1 });
+  });
+
+  it("treats a printed middle name the book lacks as a partial hit", () => {
+    const hits = suggestCustomersByName("PAMELA DENISE WAGONER", BOOK);
+    expect(hits[0]).toMatchObject({ customerId: "c1", tier: "PARTIAL" });
+    expect(hits[0].score).toBeCloseTo(2 / 3);
+  });
+
+  it("ranks the exact row above the row that merely contains it", () => {
+    // Both MCWILLIAMS rows are reachable from this name; the one that holds
+    // the middle name is the exact set and must come first.
+    const hits = suggestCustomersByName("BRIAN MICHAEL MCWILLIAMS", BOOK);
+    expect(hits.map((h) => h.customerId)).toEqual(["c2", "c3"]);
+    expect(hits[0].tier).toBe("EXACT");
+    expect(hits[1].tier).toBe("PARTIAL");
+  });
+
+  it("reaches a joint account from the one spouse the carrier printed", () => {
+    const hits = suggestCustomersByName("JERRY ESTRADA", BOOK);
+    expect(hits[0]).toMatchObject({ customerId: "c5", tier: "PARTIAL" });
+  });
+
+  it("will not reach a joint account on given names alone", () => {
+    // No surname printed: `JERRY MARILYN` overlaps ESTRADA, JERRY & MARILYN
+    // on two tokens, and matching on that would book a stranger's policy.
+    expect(suggestCustomersByName("JERRY MARILYN", BOOK)).toEqual([]);
+  });
+
+  it("matches a Spanish double surname regardless of where the comma fell", () => {
+    const [top] = suggestCustomersByName("GUILLERMO CABALLERO PRIETO", BOOK);
+    expect(top).toMatchObject({ customerId: "c6", tier: "EXACT" });
+  });
+
+  it("still matches a book row that has no comma", () => {
+    const [top] = suggestCustomersByName("STEPHANIE GREENE", BOOK);
+    expect(top).toMatchObject({ customerId: "c7", tier: "EXACT" });
+  });
+
+  it("never suggests the (SIN NOMBRE) placeholder", () => {
+    expect(suggestCustomersByName("SIN NOMBRE", BOOK)).toEqual([]);
+    expect(suggestCustomersByName("NOMBRE DEL ASEGURADO", BOOK)).toEqual([]);
+  });
+
+  it("returns nothing on a shared surname alone", () => {
+    // 185 surnames are shared by 524 customers; one token is not evidence.
+    expect(suggestCustomersByName("SMITH", BOOK)).toEqual([]);
+  });
+
+  it("returns nothing for a different person with the same surname", () => {
+    expect(suggestCustomersByName("ROBERT SMITH", BOOK)).toEqual([]);
+  });
+
+  it("refuses a page-sized blob", () => {
+    // GMX's especificación has no field labels and the parser has handed its
+    // whole first page over as the insured name.
+    const blob =
+      "ESPECIFICACION DE LA POLIZA DE SEGURO DE RESPONSABILIDAD CIVIL " +
+      "EXPEDIDA A FAVOR DE PAMELA WAGONER CON VIGENCIA DEL 01 DE ENERO";
+    expect(suggestCustomersByName(blob, BOOK)).toEqual([]);
+  });
+
+  it("caps the list", () => {
+    expect(suggestCustomersByName("BRIAN MICHAEL MCWILLIAMS", BOOK, 1)).toHaveLength(1);
+  });
+
+  it("handles a null insured name", () => {
+    expect(suggestCustomersByName(null, BOOK)).toEqual([]);
+  });
+});
+
+describe("suggestionNote", () => {
+  it("says nothing when there is nothing", () => {
+    expect(suggestionNote([])).toBeNull();
+  });
+
+  it("names a single exact hit", () => {
+    expect(suggestionNote(suggestCustomersByName("PAMELA WAGONER", BOOK))).toBe(
+      "posible cliente por nombre: WAGONER, PAMELA",
+    );
+  });
+
+  it("reports a tie rather than picking one", () => {
+    // The book really does hold EMERY, LAURA twice and KIRCHHOFF, CINDY
+    // three times.
+    const dupes: CustomerNameRow[] = [
+      { id: "d1", name: "EMERY, LAURA" },
+      { id: "d2", name: "EMERY, LAURA" },
+    ];
+    expect(suggestionNote(suggestCustomersByName("LAURA EMERY", dupes))).toBe(
+      "2 clientes tienen ese mismo nombre; elija cuál",
+    );
+  });
+
+  it("lists partial hits", () => {
+    expect(suggestionNote(suggestCustomersByName("PAMELA DENISE WAGONER", BOOK))).toBe(
+      "posibles clientes por nombre: WAGONER, PAMELA",
+    );
+  });
+});

apps/api/src/policy-ocr/name-matcher.ts

@@ -0,0 +1,199 @@
+/**
+ * Suggests which existing customer a printed insured name belongs to.
+ *
+ * The office books customers surname-first ("WAGONER, PAMELA") and carriers
+ * print them given-name-first ("PAMELA DENISE WAGONER"), so a string compare
+ * never hits. Comparing *token sets* does, and it is order-insensitive by
+ * construction — which is the whole trick.
+ *
+ * **These are suggestions, never matches.** Nothing here sets
+ * `matchedCustomerId` or `confident`; the review screen offers the ranked
+ * names and a human picks. That line is not caution, it is what the book
+ * measures out to: of 1536 customers, 1487 have a distinct normalized token
+ * set — but loosen the rule to surname + first given name only and 131 of
+ * them (8.5%) collide, because the book holds `MCWILLIAMS, BRIAN MICHAEL`
+ * *and* `MCWILLIAMS, BRIAN`, and `CUADROS, JORGE JR` alongside three
+ * `CUADROS, JORGE H.`. 185 surnames are shared by 524 customers, so a
+ * surname alone carries no information at all.
+ *
+ * The two tiers below are drawn at the two places that measurement puts a
+ * cliff: full token-set equality, where cross-person collisions are
+ * effectively zero, and strict containment, where they are common enough
+ * that the result can only ever be a hint.
+ */
+
+/** A customer row as the matcher needs it — id and the book's name. */
+export interface CustomerNameRow {
+  id: string;
+  name: string;
+}
+
+export type NameMatchTier = "EXACT" | "PARTIAL";
+
+export interface CustomerNameSuggestion {
+  customerId: string;
+  customerName: string;
+  /**
+   * `EXACT` — the two names carry the same tokens, in any order.
+   * `PARTIAL` — one name's tokens are all present in the other's, plus the
+   * surname. A printed middle name the book does not hold, or a joint
+   * account where the carrier named one spouse, both land here.
+   */
+  tier: NameMatchTier;
+  /** Shared tokens over the longer name's token count, 0..1. */
+  score: number;
+}
+
+/**
+ * Words that carry no identity. Spanish particles and the ampersand joining
+ * a couple are noise; the corporate suffixes are dropped so `S.A. DE C.V.`
+ * does not make every company look alike.
+ */
+const NOISE = new Set([
+  "DE", "DEL", "LA", "LAS", "LOS", "Y", "AND", "VDA",
+  "JR", "SR", "II", "III", "IV",
+  "SA", "CV", "SAPI", "SRL", "RL", "SC", "INC", "LLC", "LTD", "CORP", "CO",
+]);
+
+/**
+ * Placeholder rows the migration left behind. Fourteen customers are named
+ * literally `(SIN NOMBRE)`; without this they would be one 14-way tie on
+ * every unreadable name.
+ */
+const PLACEHOLDER = new Set(["SIN NOMBRE", "NOMBRE SIN"]);
+
+/**
+ * A name blob longer than this is not a name. GMX's PVL especificación has
+ * no field labels, and the parser has been seen handing its entire first
+ * page over as `insuredName`; matching that against the book would find
+ * a surname somewhere in the prose and suggest a stranger.
+ */
+const MAX_TOKENS = 8;
+const MAX_CHARS = 80;
+
+/**
+ * Splits a name into comparable tokens.
+ *
+ * Accents go first, and deliberately in both directions: the book holds
+ * `MUÑOZ` where OCR routinely reads `MUNOZ`, and folding both to the same
+ * ASCII makes that a hit rather than a miss.
+ *
+ * Tokens containing digits are dropped outright. ANA's automobile face
+ * prints the phone number hard against the insured name — the parser has
+ * emitted `MARIA GARCIA Ph.3102001538` — and the digits would otherwise
+ * be an extra token forever blocking `EXACT`.
+ *
+ * Single letters are dropped as initials: the book is full of
+ * `WEAKLAND, RICHARD E.`, and a carrier that prints the middle name in
+ * full should still match the row that abbreviates it.
+ */
+export function nameTokens(raw: string): string[] {
+  const cleaned = raw
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, " ")
+    .trim();
+
+  const tokens = cleaned
+    .split(" ")
+    .filter((t) => t.length > 1 && !/\d/.test(t) && !NOISE.has(t));
+
+  return [...new Set(tokens)];
+}
+
+/** The surname tokens — everything before the comma the book writes. */
+function surnameTokens(bookName: string): string[] {
+  const comma = bookName.indexOf(",");
+  // 54 of 1536 rows have no comma at all ("GREENE STEPHANIE",
+  // "FAROOQ VAKIL"), and which half is the surname is unknowable. Requiring
+  // a surname we cannot identify would silently exclude those rows, so they
+  // fall back to requiring nothing beyond the containment rule.
+  if (comma < 0) return [];
+  return nameTokens(bookName.slice(0, comma));
+}
+
+function isPlaceholder(tokens: string[]): boolean {
+  return tokens.length === 0 || PLACEHOLDER.has([...tokens].sort().join(" "));
+}
+
+function containsAll(haystack: Set<string>, needles: string[]): boolean {
+  return needles.every((n) => haystack.has(n));
+}
+
+/**
+ * Ranks the book against one printed name.
+ *
+ * Returns at most `limit` suggestions, `EXACT` before `PARTIAL` and higher
+ * score first. An empty array means the printed name was unusable (too
+ * long, too few real tokens) or nothing in the book came close — both of
+ * which leave the review screen exactly as it is today.
+ */
+export function suggestCustomersByName(
+  printedName: string | null | undefined,
+  customers: CustomerNameRow[],
+  limit = 3,
+): CustomerNameSuggestion[] {
+  if (!printedName || printedName.length > MAX_CHARS) return [];
+
+  const printed = nameTokens(printedName);
+  // One usable token is a surname or a given name on its own, and 34% of the
+  // book shares a surname with someone. Nothing useful can come of it.
+  if (printed.length < 2 || printed.length > MAX_TOKENS) return [];
+
+  const printedSet = new Set(printed);
+  const out: CustomerNameSuggestion[] = [];
+
+  for (const c of customers) {
+    const book = nameTokens(c.name);
+    if (isPlaceholder(book) || book.length < 2) continue;
+
+    const bookSet = new Set(book);
+    const overlap = printed.filter((t) => bookSet.has(t)).length;
+    // Two shared tokens is the floor: one is a bare surname collision.
+    if (overlap < 2) continue;
+
+    const bookInPrinted = containsAll(printedSet, book);
+    const printedInBook = containsAll(bookSet, printed);
+    if (!bookInPrinted && !printedInBook) continue;
+
+    // When the book's name is the shorter one, containment already proves
+    // the surname was printed. When the printed name is shorter — the book
+    // holds a middle name or a second spouse the carrier omitted — the
+    // surname must be there explicitly, or `JERRY MARILYN` would match
+    // `ESTRADA, JERRY & MARILYN` on given names alone.
+    if (!bookInPrinted && !containsAll(printedSet, surnameTokens(c.name))) continue;
+
+    out.push({
+      customerId: c.id,
+      customerName: c.name,
+      tier: bookInPrinted && printedInBook ? "EXACT" : "PARTIAL",
+      score: overlap / Math.max(book.length, printed.length),
+    });
+  }
+
+  out.sort((a, b) => {
+    if (a.tier !== b.tier) return a.tier === "EXACT" ? -1 : 1;
+    if (b.score !== a.score) return b.score - a.score;
+    return a.customerName.localeCompare(b.customerName);
+  });
+
+  return out.slice(0, limit);
+}
+
+/** Review-queue wording for what the suggestions amount to. */
+export function suggestionNote(suggestions: CustomerNameSuggestion[]): string | null {
+  if (suggestions.length === 0) return null;
+
+  const exact = suggestions.filter((s) => s.tier === "EXACT");
+  // More than one exact hit is the duplicate-customer case the book really
+  // has (`EMERY, LAURA` twice, `KIRCHHOFF, CINDY` three times). Saying so is
+  // more useful than naming whichever one sorted first.
+  if (exact.length > 1) {
+    return `${exact.length} clientes tienen ese mismo nombre; elija cuál`;
+  }
+  if (exact.length === 1) {
+    return `posible cliente por nombre: ${exact[0].customerName}`;
+  }
+  return `posibles clientes por nombre: ${suggestions.map((s) => s.customerName).join(", ")}`;
+}

apps/api/src/policy-ocr/parsers/policy-parser.spec.ts

@@ -15,6 +15,11 @@ function page(text: string): OcrPage {
   return { text, words: [], confidence: 0.95 };
 }
 
+/** Coverages keyed by their risk label, so an assertion names the coverage
+ *  it is about instead of an array index that shifts when one is added. */
+const byRisk = (p: ReturnType<typeof parsePolicy>): Record<string, ParsedCoverage> =>
+  Object.fromEntries(p.coverages.map((c) => [c.risk, c]));
+
 describe("detectPolicyProvider", () => {
   it("claims GMX from the brand wordmark on the letterhead", () => {
     expect(
@@ -111,6 +116,13 @@ describe("parsePolicy / GMX", () => {
     expect(p.coverages.length).toBeGreaterThan(10);
   });
 
+  it("names the product MULT for confirm to resolve", () => {
+    // The caratula's own header reads "Multiple Policy / Home". MULT is the
+    // legacy discriminator for that multi-line home policy; INCENDIO is
+    // fire-only and no policy in the book has ever used it.
+    expect(parsePolicy(GMX_FULL).policyTypeName).toBe("MULT");
+  });
+
   it("leaves premium fields null on the certificate page and notes it", () => {
     const p = parsePolicy(GMX_FULL);
     expect(p.netPremium).toBeNull();
@@ -145,3 +157,778 @@ describe("parsePolicy / GMX", () => {
     expect(eqTyped.lossParticipation).toBe("20%");
   });
 });
+
+/**
+ * The second GMX document family: the Spanish PVL "especificación" the office
+ * receives as `…-CondicionesParticulares.pdf`. Verbatim excerpts from
+ * `007_LGS-HGMX_07006957_01_0-CondicionesParticulares.pdf` through
+ * `pdftotext -layout`, indentation included — the column positions and the
+ * blank lines between blocks are what the parser reads, so a cleaned-up
+ * fixture would test nothing.
+ */
+describe("parsePolicy / GMX especificación (PVL Hogar)", () => {
+  const HEADER =
+    "                    ESPECIFICACIÓN QUE SE ADHIERE Y FORMA PARTE INTEGRANTE DE LA PÓLIZA\n" +
+    "                                           07-037-07006957-00000-01\n" +
+    "\n";
+
+  const GMX_ESPEC = page(
+    HEADER +
+      "\n" +
+      "                                            Nombre del asegurado EMMER . KATHLEEN\n" +
+      "\n" +
+      "                                          Tipo Persona Asegurada Propietario\n" +
+      "\n" +
+      "                                               Ubicación del riesgo LOS PELICANOS ESTE NO. 98 Col. LAS GAVIOTAS PLAYAS\n" +
+      "                                                                    DE ROSARITO BAJA CALIFORNIA 22713\n" +
+      "\n" +
+      "                                      Características del Inmueble Casa Tipo constructivo Combinado: Macizo y Madera.\n" +
+      "                                                                   Consta de 2 pisos incluyendo sótanos y planta baja.\n" +
+      "\n" +
+      "                                             -500 mts.cuerpo agua SI\n" +
+      "\n" +
+      "                                              Asegurado Adicional\n" +
+      "\n" +
+      "PVL Hogar - GMX Seguros                                                     Página: 1 de 10\n" +
+      HEADER +
+      "\n" +
+      " SECCIÓN INCENDIO EDIFICIO Y CONTENIDOS\n" +
+      "\n" +
+      " EDIFICIO\n" +
+      "\n" +
+      " Límite Máximo de Responsabilidad:\n" +
+      " $200,000.00 USD\n" +
+      "\n" +
+      " Quedan amparados los muros de contención y bardas, así como puertas y portones, hasta un sublimite de $ 50,000.00 M.N. o su\n" +
+      " equivalente en dólares americanos, o hasta el 10% de la suma asegurada de la sección de Edificio, lo que resulte menor.\n" +
+      "\n" +
+      "\n" +
+      " CONTENIDOS\n" +
+      "\n" +
+      " Límite Máximo de Responsabilidad:\n" +
+      " $20,000.00 USD\n" +
+      "\n" +
+      "    2. Terremoto o erupción volcánica: Sección Edificio EXCLUIDO, Sección Contenidos EXCLUIDO\n" +
+      "\n" +
+      "    3. Fenómenos hidrometeorológicos: Sección Edificio $200,000.00 USD, Sección Contenidos $20,000.00 USD\n" +
+      "\n" +
+      " Riesgos adicionales.\n" +
+      "\n" +
+      " Remoción de escombros\n" +
+      "\n" +
+      "    Límite Máximo de Responsabilidad:\n" +
+      "    Edificio\n" +
+      "    $20,000.00 USD\n" +
+      "    Contenidos\n" +
+      "    $2,000.00 USD\n" +
+      "\n" +
+      " Gastos extraordinarios para casa habitación\n" +
+      "\n" +
+      " En caso de siniestro por los riesgos cubiertos en esta póliza, GMX Seguros pagará la renta de casa o departamento, casa de\n" +
+      " huéspedes u hotel cuando se asegure el inmueble, así como los gastos de mudanza, seguro de transporte del menaje de casa y\n" +
+      " efectuados.\n" +
+      "\n" +
+      "    Límite Máximo de Responsabilidad:\n" +
+      "    $22,000.00 USD\n" +
+      "    Periodo de indemnización: 4 meses.\n" +
+      "\n" +
+      " Bienes a la Intemperie:\n" +
+      "\n" +
+      "\n" +
+      "     5 POR CIENTO SOBRE SUMA ASEGURADA, 20 PORCIENTO DE PARTICIPACIÓN A CARGO DEL ASEGURADO DE TODA\n" +
+      "     Y CADA PÉRDIDA.\n" +
+      "\n" +
+      "\n" +
+      "     Límite Máximo de Responsabilidad: $10,000.00 USD\n" +
+      "\n" +
+      " DEDUCIBLES:\n" +
+      "\n" +
+      " El procedimiento que se seguirá para la aplicación de deducibles en caso de que la póliza cuente con cláusula inflacionaria en todas\n" +
+      " y/o en algunas de sus coberturas será como sigue:\n" +
+      "\n" +
+      " Fenómenos hidrometeorológicos\n" +
+      " Zona: A2\n" +
+      " Deducible\n" +
+      "     Edificio: 1 POR CIENTO SOBRE SUMA ASEGURADA\n" +
+      "     Coaseguro:\n" +
+      "     Zona 1: (INTERIOR) Participación a cargo del asegurado del 10% de toda y cada pérdida.\n" +
+      "     Zona 2: Participación a cargo del asegurado del 10% de toda y cada pérdida.\n" +
+      "\n" +
+      "     Deducible\n" +
+      "     Contenidos: 1 POR CIENTO SOBRE SUMA ASEGURADA\n" +
+      "\n" +
+      " II.- SECCIÓN DIVERSOS MISCELÁNEOS\n" +
+      "\n" +
+      " ROBO DE CONTENIDOS\n" +
+      "\n" +
+      " Límite de Responsabilidad:\n" +
+      " $4,000.00 USD\n" +
+      "\n" +
+      "\n" +
+      " Deducible:\n" +
+      " Sin deducible\n" +
+      "\n" +
+      "\n" +
+      " Sublímites:\n" +
+      " Joyas, artículos de oro y plata, armas, relojes, pieles, piedras preciosas montadas, colecciones, obras de arte y demás que por su\n" +
+      "\n" +
+      "PVL Hogar - GMX Seguros                                                     Página: 7 de 10\n" +
+      HEADER +
+      "\n" +
+      " naturaleza se consideran como objetos de difícil o imposible reposición\n" +
+      "\n" +
+      "\n" +
+      " Límite de Responsabilidad:\n" +
+      "\n" +
+      " $2,000.00 USD\n" +
+      "\n" +
+      "\n" +
+      " Deducible:\n" +
+      " Sin deducible\n" +
+      "\n" +
+      " Las condiciones generales que forman parte de la presente póliza son las identificadas bajo el nombre:\n" +
+      " W_HogarGMX_12.11.2025.pdf\n" +
+      "\n" +
+      "PVL Hogar - GMX Seguros                                                    Página: 10 de 10\n",
+  );
+
+  it("reads a policy number whose groups are not the caratula's widths", () => {
+    // 2-3-8-5-2 here vs 3-3-8-4-2 on the English caratula. Pinning the widths
+    // reads one family and returns null on the other.
+    expect(parsePolicy(GMX_ESPEC).policyNumber).toBe("07-037-07006957-00000-01");
+  });
+
+  it("reads the insured, the risk location across its wrapped line, and the ZIP", () => {
+    const p = parsePolicy(GMX_ESPEC);
+    expect(p.provider).toBe("GMX");
+    expect(p.insuredName).toBe("EMMER . KATHLEEN");
+    expect(p.legalAddress).toBe(
+      "LOS PELICANOS ESTE NO. 98 Col. LAS GAVIOTAS PLAYAS DE ROSARITO BAJA CALIFORNIA 22713",
+    );
+    expect(p.zip).toBe("22713");
+    // The cell is printed but empty on this policy — an empty label must not
+    // capture the next line of the form.
+    expect(p.additionalInsured).toBeNull();
+  });
+
+  it("leaves the fields this document does not carry null, and says so", () => {
+    const p = parsePolicy(GMX_ESPEC);
+    expect(p.policyFrom).toBeNull();
+    expect(p.policyTo).toBeNull();
+    expect(p.policyDate).toBeNull();
+    expect(p.agentName).toBeNull();
+    expect(p.netPremium).toBeNull();
+    expect(p.total).toBeNull();
+    // The note must tell the reviewer to key them in — those three are
+    // captured by hand on this layout — and must say what silently breaks if
+    // the vigencia is left empty.
+    const notes = p.notes.join(" ");
+    expect(notes).toMatch(/no trae vigencia, agente ni prima/i);
+    expect(notes).toMatch(/captúrelos a mano/i);
+    expect(notes).toMatch(/avisos de renovación/i);
+  });
+
+  it("takes the currency from the printed limits, not from the M.N. sublimits", () => {
+    // The body prose quotes sublimits in pesos ("$ 50,000.00 M.N."); every
+    // limit is in USD, and only the limits vote.
+    expect(parsePolicy(GMX_ESPEC).currency).toBe("USD");
+  });
+
+  it("reads each coverage under its own heading", () => {
+    const c = byRisk(parsePolicy(GMX_ESPEC));
+    expect(c.EDIFICIO?.insuredAmount).toBe(200000);
+    expect(c.CONTENIDOS?.insuredAmount).toBe(20000);
+    expect(c["ROBO DE CONTENIDOS"]?.insuredAmount).toBe(4000);
+    expect(c["ROBO DE CONTENIDOS"]?.deductible).toBe("Sin deducible");
+  });
+
+  it("splits a limit printed under Edificio / Contenidos sub-labels", () => {
+    const c = byRisk(parsePolicy(GMX_ESPEC));
+    expect(c["Remoción de escombros — Edificio"]?.insuredAmount).toBe(20000);
+    expect(c["Remoción de escombros — Contenidos"]?.insuredAmount).toBe(2000);
+  });
+
+  it("names a coverage after its heading, not after the wrapped tail of the prose above it", () => {
+    // Walking back from the limit hits "efectuados." — short, and the only
+    // thing separating it from a heading is that it is not preceded by a
+    // blank line.
+    const c = byRisk(parsePolicy(GMX_ESPEC));
+    expect(c["Gastos extraordinarios para casa habitación"]?.insuredAmount).toBe(22000);
+    expect(c["efectuados."]).toBeUndefined();
+  });
+
+  it("reads a limit printed on the label's own line", () => {
+    const c = byRisk(parsePolicy(GMX_ESPEC));
+    expect(c["Bienes a la Intemperie"]?.insuredAmount).toBe(10000);
+  });
+
+  it("reads a deductible stated as a sentence above the limit", () => {
+    const c = byRisk(parsePolicy(GMX_ESPEC));
+    expect(c["Bienes a la Intemperie"]?.deductible).toBe(
+      "5 POR CIENTO SOBRE SUMA ASEGURADA, 20 PORCIENTO DE PARTICIPACIÓN A CARGO DEL ASEGURADO DE TODA Y CADA PÉRDIDA.",
+    );
+  });
+
+  it("never borrows a neighbouring coverage's prose as a deductible", () => {
+    // "…o hasta el 10% de la suma asegurada de la sección de Edificio" is a
+    // sublimit rule for EDIFICIO, printed two paragraphs above CONTENIDOS.
+    const c = byRisk(parsePolicy(GMX_ESPEC));
+    expect(c.CONTENIDOS?.deductible).toBeNull();
+    expect(c.EDIFICIO?.deductible).toBeNull();
+  });
+
+  it("does not read the page-level DEDUCIBLES paragraph as a deductible", () => {
+    const p = parsePolicy(GMX_ESPEC);
+    expect(
+      p.coverages.some((c) => (c.deductible ?? "").includes("cláusula inflacionaria")),
+    ).toBe(false);
+  });
+
+  it("reads a sublimit block as a sublimit OF the coverage above it", () => {
+    // The amount sits after a blank line AND a page break, and the block's
+    // own heading ("Sublímites:") names no risk.
+    const c = byRisk(parsePolicy(GMX_ESPEC));
+    expect(c["ROBO DE CONTENIDOS — sublímite"]?.insuredAmount).toBe(2000);
+  });
+
+  it("records an excluded catastrophic risk as excluded, never as zero", () => {
+    const p = parsePolicy(GMX_ESPEC);
+    const quake = p.coverages.filter((c) => /Terremoto/i.test(c.risk));
+    expect(quake).toHaveLength(2);
+    for (const c of quake) {
+      expect(c.risk).toMatch(/EXCLUIDO/);
+      // A coverage insured for $0 and an excluded coverage are the same
+      // number and very different facts.
+      expect(c.insuredAmount).toBeNull();
+    }
+  });
+
+  it("attaches the hydrometeorological deductible and coinsurance from its own block", () => {
+    const c = byRisk(parsePolicy(GMX_ESPEC));
+    const building = c["Fenómenos hidrometeorológicos — Sección Edificio"];
+    expect(building?.insuredAmount).toBe(200000);
+    expect(building?.deductible).toBe("1 POR CIENTO SOBRE SUMA ASEGURADA");
+    expect(building?.lossParticipation).toBe("10%");
+    expect(c["Fenómenos hidrometeorológicos — Sección Contenidos"]?.insuredAmount).toBe(20000);
+  });
+
+  it("names the same product as the caratula — one policy, two artifacts", () => {
+    expect(parsePolicy(GMX_ESPEC).policyTypeName).toBe("MULT");
+  });
+
+  it("carries the underwriting context the fields have no home for", () => {
+    const notes = parsePolicy(GMX_ESPEC).notes.join(" | ");
+    expect(notes).toMatch(/tipo de persona asegurada: Propietario/);
+    expect(notes).toMatch(/características del inmueble: Casa/);
+    expect(notes).toMatch(/cuerpo de agua/);
+    expect(notes).toMatch(/zona catastrófica declarada: A2/);
+    expect(notes).toMatch(/W_HogarGMX_12\.11\.2025\.pdf/);
+  });
+});
+
+/* ------------------------------------------------------------------ ANA */
+
+/**
+ * Verbatim `pdftotext -layout` output of the PDFs A.N.A.'s portal produced
+ * for three real policies, cut at the end of the risk table (the legal
+ * boilerplate and the repeated AGENT COPY below it are not parsed, and the
+ * repeats are covered by their own test).
+ *
+ * The column padding is load-bearing on the driver's policy, which
+ * distinguishes SUM INSURED from PREMIUM by horizontal position alone — do
+ * not reflow these strings.
+ */
+
+const ANA_AUTO_AMPLIA = page(`A.N.A. COMPAÑIA DE SEGUROS SA DE CV
+LUIS CABRERA #2033 INT. 201, Col. ZONA URBANA RIO TIJUANA
+C.P. 22010 MUNICIPIO DE TIJUANA, BAJA CALIFORNIA
+www.anaseguros.com.mx
+AUTOMOBILE
+                                       ALL CLAIMS MUST BE REPORTED BEFORE LEAVING MEXICO
+U.S. CELL PHONES TRY      + 011-52-55-5322-82-66 MEXICAN CELL PHONES 800-911-911-9                                                   SPECIAL POLICY FOR TOURISTS
+TOLL-FREE FROM THE U.S.A. 888-335-7072           BELIZE CELL PHONES 00-52-55-5322-8266
+WHATSAPP                  + 52-55-80-50-3633
+                                                                                                                            No.           700489651
+                   ISSUED BY:                               DATE ISSUED                                   TERM OF INSURANCE
+                                                                                                                                                                  DAYS
+JORGE HUMBERTO CUADROS                                     DAY MONTH YEAR                                DAY    MONTH    YEAR                        TIME
+BENITO JUAREZ 25 No.50 INT 38 CENTRO
+                                                            04         08      2026 FROM                  07             08            2026          12:01
+                                                                                                                                                                     365
+ROSARITO, BAJA CALIFORNIA 22710
+.                                                70175                                 TO                 07             08            2027          12:01
+         DISCOUNT                   PREMIUM                     POLICY FEE                        TAX                     LOCAL TAX                        TOTAL
+              -                       298.61                        30.00                        26.29                          0.00                       354.90
+
+    INSURED                  RAY DEAN II AND SUSAN ROCKHOLD
+                                                                                                                     LICENSE           P0066762
+    ADDRESS                  10308 DONNA AVE                                                                         EMAIL             PROLABSALE@AOL.COM
+    CITY & STATE             NORTHRIDGE, CA                                                             91326        TELEPHONE 8184453524
+                                                                                                                                                  PAYMENT DEADLINE
+  INSURANCE COMPANY                                                              LIEN HOLDER
+                                                                                                                                                        IMMEDIATE
+
+      ITEM                   YEAR             MAKE                                      BODY                                    SERIAL No.                     PLATES
+VEHICLE                      2017           CHRYSLER                                  PACIFICA                              2C4RC1DG7HR654698                  8BPX206
+TRAILER                                                                                                                             .                             .
+TOWING                                                                                                                              .                             .
+*** VALUE STATED MUST NOT EXCEED MARKET VALUE ***
+***VEHICLES THAT HAVE BEEN ACQUIRED AS SALVAGE, REBUILT, OR HAVE BEEN USED PREVIOUSLY AS A TAXI WILL BE CONSIDERED WITH A REDUCED VALUE OF 35% (thirty-five percent), TAKING
+AS A BASE THE VALUE OF A SIMILAR NORMAL VEHICLE, THAT IS, ONE THAT HAS NOT BEEN ACQUIRED AS SALVAGE AND ITS PREVIOUS USE HAS NOT BEEN AS A TAXI OR REBUILT. IT WILL BE THE
+SOLE OBLIGATION AND RESPONSIBILITY OF THE INSURED TO DECLARATE THIS WHEN ACQUIRING THE POLICY.
+SECTION                                     SPECIFICATION OF RISKS                                                                              LIMIT OF LIABILITY
+            MATERIAL DAMAGE WITH MANDATORY DEDUCTIBLE                                                            COVERED/EXCLUDED VEHICLE                   8,000.00 DLLS.
+    1       DEDUCTIBLE: WITH MINIMUM OF $500.00 ON AUTOS
+                                                                                                                                              TRAILER
+            (SEDANS, COUPES, CONVERTIBLES AND STATION WAGONS)                                                         COVERED
+            AND $500.00 ON ALL OTHERS (PICK UPS, VANS, SUV´s AND MOTOR HOMES).                                                                                  0.00 DLLS.
+
+            TOTAL THEFT WITH MANDATORY DEDUCTIBLE                                                                COVERED/EXCLUDED TOWING
+    2       DEDUCTIBLE: WITH MINIMUM OF $1,000.00 ON AUTOS                                                                                                      0.00 DLLS.
+            (SEDANS, COUPES, CONVERTIBLES AND STATION WAGONS)                                                         COVERED
+            AND $1,000.00 ON ALL OTHERS (PICK UPS, VANS, SUV´s AND MOTOR HOMES).
+            LIABILITY FOR PROPERTY DAMAGE TO THIRD PARTIES
+    3                                                                                                                                               100,000.00         DLLS.
+
+
+            BODILY INJURY LIABILITY                                                               PER                               PER
+    4                                                                                             PERSON         100,000.00         ACCIDENT        200,000.00         DLLS.
+
+            MEDICAL EXPENSES                                                                      PER                               PER
+    5                                                                                             PERSON         5,000.00           ACCIDENT        25,000.00          DLLS.
+
+                                                                                                                 COVERED/EXCLUDED                       PREMIUM
+    6       A.N.A.'s LEGAL AID
+                                                                                                                      COVERED                             40.00
+                                                                                                                 COVERED/EXCLUDED                       PREMIUM
+     7      A.N.A.'s ROADSIDE ASSISTANCE
+                                                                                                                      COVERED                             40.00
+            CATASTROPHIC LIABILITY FOR DEATH OF THIRD                                                                                                   PREMIUM
+     8                                                                                                          EXCLUDED
+            PARTIES                                                                                                                    DLLS.               0.00
+            ELITE OR ELITE PLUS WITH MANDATORY DEDUCTIBLE                                                          COVERED/EXCLUDED
+     9     PARTIAL THEFT (LIMIT 0.00 DLLS.WITH DEDUCTIBLE: 0.00 DLLS. PER EVENT)                                                                           0.00
+           VANDALISM (LIMIT 0.00 DLLS.WITH DEDUCTIBLE: 0.00 DLLS. PER EVENT)                                           EXCLUDED
+
+
+ISSUED ONLINE`);
+
+const ANA_AUTO_RC_DIAS = page(`A.N.A. COMPAÑIA DE SEGUROS SA DE CV
+LUIS CABRERA #2033 INT. 201, Col. ZONA URBANA RIO TIJUANA
+C.P. 22010 MUNICIPIO DE TIJUANA, BAJA CALIFORNIA
+www.anaseguros.com.mx
+AUTOMOBILE
+                                       ALL CLAIMS MUST BE REPORTED BEFORE LEAVING MEXICO
+U.S. CELL PHONES TRY      + 011-52-55-5322-82-66 MEXICAN CELL PHONES 800-911-911-9                                                   SPECIAL POLICY FOR TOURISTS
+TOLL-FREE FROM THE U.S.A. 888-335-7072           BELIZE CELL PHONES 00-52-55-5322-8266
+WHATSAPP                  + 52-55-80-50-3633
+                                                                                                                            No.           700487807
+                   ISSUED BY:                               DATE ISSUED                                   TERM OF INSURANCE
+                                                                                                                                                                         DAYS
+JORGE HUMBERTO CUADROS DIARIA                              DAY MONTH YEAR                                DAY    MONTH    YEAR                            TIME
+BENITO JUAREZ 25 NO50 INT 38 COL CENTRO
+                                                            22         07      2026 FROM                  23             07            2026              12:01
+                                                                                                                                                                            3
+ROSARITO BAJA CALIFORNIA 22710
+(661) 612 12 55                                  70175                                 TO                 26             07            2026              12:01
+         DISCOUNT                   PREMIUM                     POLICY FEE                        TAX                     LOCAL TAX                             TOTAL
+              -                        10.77                        25.00                         2.86                          0.00                              38.63
+
+    INSURED                  STEPHEN RUPAN SHATAFIAN
+                                                                                                                     LICENSE           C1394198
+    ADDRESS                  13181 CROSSROADS PARKWAY NORTH STE 300                                                  EMAIL             sshatafian@lee-associates.com
+
+
+    CITY & STATE             CITY OF INDUSTRY, CA                                                        91746       TELEPHONE 7143221072
+                                                                                                                                                     PAYMENT DEADLINE
+  INSURANCE COMPANY                                                              LIEN HOLDER
+                                                                                                                                                            IMMEDIATE
+
+      ITEM                   YEAR               MAKE                                    BODY                                    SERIAL No.                             PLATES
+VEHICLE                      2022               FORD                                   TRANSIT                              1FBAX2CG3NKA69091                          EC46T99
+TRAILER                                                                                                                             .                                     .
+TOWING                                                                                                                              .                                     .
+*** VALUE STATED MUST NOT EXCEED MARKET VALUE ***
+***VEHICLES THAT HAVE BEEN ACQUIRED AS SALVAGE, REBUILT, OR HAVE BEEN USED PREVIOUSLY AS A TAXI WILL BE CONSIDERED WITH A REDUCED VALUE OF 35% (thirty-five percent), TAKING
+AS A BASE THE VALUE OF A SIMILAR NORMAL VEHICLE, THAT IS, ONE THAT HAS NOT BEEN ACQUIRED AS SALVAGE AND ITS PREVIOUS USE HAS NOT BEEN AS A TAXI OR REBUILT. IT WILL BE THE
+SOLE OBLIGATION AND RESPONSIBILITY OF THE INSURED TO DECLARATE THIS WHEN ACQUIRING THE POLICY.
+SECTION                                     SPECIFICATION OF RISKS                                                                                LIMIT OF LIABILITY
+            MATERIAL DAMAGE WITH MANDATORY DEDUCTIBLE                                                            COVERED/EXCLUDED VEHICLE                              0.00 DLLS.
+    1       DEDUCTIBLE: ON AUTOS (SEDANS, COUPES, CONVERTIBLES AND
+                                                                                                                                               TRAILER
+            STATION WAGONS) AND OTHERS (PICK UPS, VANS,                                                              EXCLUDED
+            SUV´s AND MOTOR HOMES).                                                                                                                                    0.00 DLLS.
+
+            TOTAL THEFT WITH MANDATORY DEDUCTIBLE                                                                COVERED/EXCLUDED TOWING
+    2       DEDUCTIBLE: ON AUTOS (SEDANS, COUPES, CONVERTIBLES AND                                                                                                     0.00 DLLS.
+            STATION WAGONS) AND OTHERS (PICK UPS, VANS,                                                              EXCLUDED
+            SUV´s AND MOTOR HOMES).
+            LIABILITY FOR PROPERTY DAMAGE TO THIRD PARTIES
+    3                                                                                                                                                  100,000.00            DLLS.
+
+
+            BODILY INJURY LIABILITY                                                               PER                               PER
+    4                                                                                             PERSON         100,000.00         ACCIDENT           200,000.00            DLLS.
+
+            MEDICAL EXPENSES                                                                      PER                               PER
+    5                                                                                             PERSON         5,000.00           ACCIDENT           25,000.00             DLLS.
+
+                                                                                                                 COVERED/EXCLUDED                            PREMIUM
+    6       A.N.A.'s LEGAL AID
+                                                                                                                      COVERED                                    2.25
+                                                                                                                 COVERED/EXCLUDED                            PREMIUM
+     7      A.N.A.'s ROADSIDE ASSISTANCE
+                                                                                                                      COVERED                                    2.25
+            CATASTROPHIC LIABILITY FOR DEATH OF THIRD                                                                                                        PREMIUM
+     8                                                                                                           EXCLUDED
+            PARTIES                                                                                                                    DLLS.                     0.00
+            ELITE OR ELITE PLUS WITH MANDATORY DEDUCTIBLE                                                          COVERED/EXCLUDED
+     9     PARTIAL THEFT (LIMIT 0.00 DLLS.WITH DEDUCTIBLE: 0.00 DLLS. PER EVENT)                                                                                 0.00
+           VANDALISM (LIMIT 0.00 DLLS.WITH DEDUCTIBLE: 0.00 DLLS. PER EVENT)                                           EXCLUDED
+
+
+ISSUED ONLINE`);
+
+const ANA_LICENCIA = page(`A.N.A. COMPAÑIA DE SEGUROS SA DE CV
+LUIS CABRERA #2033 INT. 201, Col.4 ZONA URBANA RIO TIJUANA
+C.P. 22010 MUNICIPIO DE TIJUANA, BAJA CALIFORNIA
+www.anaseguros.com.mx
+                                                 DRIVER´S POLICY FOR AUTOMOBILE
+                                       ALL CLAIMS MUST BE REPORTED BEFORE LEAVING MEXICO
+U.S. CELL PHONES TRY      + 011-52-55-5322-82-66 MEXICAN CELL PHONES 800-911-911-9
+                                                                                                                                          SPECIAL POLICY FOR TOURISTS
+TOLL-FREE FROM THE U.S.A. 888-335-7072           BELIZE CELL PHONES 00-52-55-5322-8266
+WHATSAPP                  + 52-55-80-50-3633                                                                                     No.            700489616
+                   ISSUED BY:                              DATE ISSUED & TIME                                 TERM OF INSURANCE
+JORGE HUMBERTO CUADROS
+                                                                                                                                                                          DAYS
+                                                            DAY MONTH YEAR                                   DAY    MONTH    YEAR                           TIME
+BENITO JUAREZ 25 No.50 INT 38 CENTRO                          04         08      2026 FROM                     06             08            2026            12:01
+                                                                                                                                                                            365
+ROSARITO, BAJA CALIFORNIA 22710                                                           TO                   06             08            2027            12:01
+.                                                 70175
+      DISCOUNT                      PREMIUM                      POLICY FEE                           TAX                      LOCAL TAX                         TOTAL
+             -                        142.78                           30.00                         13.82                           0.00                         186.60
+
+   LICENSE           N0017668                                    EMAIL          PWAGONER49@AOL.COM                        TELEPHONE 3102001538
+       POLICY HOLDER
+      1. NAME          :                   PAMELA DENISE WAGONER        Ph.3102001538
+        ADDRESS        :                   49305 HIGHWAY 74 SPC 10, PALM DESERT, CA, 92260,
+        DRIVER LICENSE :                   N0017668
+      2. NAME          :
+        ADDRESS        :
+        DRIVER LICENSE :
+                                             NONE
+      3. NAME          :
+        ADDRESS        :
+        DRIVER LICENSE :
+                                             NONE
+      4. NAME          :
+        ADDRESS        :
+        DRIVER LICENSE :                     NONE
+      5. NAME          :
+        ADDRESS        :
+        DRIVER LICENSE :                     NONE
+     SPECIFICATION OF RISKS                                                                                    SUM INSURED                                     PREMIUM
+     LIABILITY FOR PROPERTY DAMAGE TO THIRD PARTIES                                                     100,000.00 usd.                                      18.70         usd.
+     BODILY INJURY LIABILITY ( EXCLUDING OCCUPANTS OF THE VEHICLE )                                     100,000.00 usd. Per Person
+                                                                                                                                                             54.27         usd.
+                                                                                                        200,000.00 usd. Per Accident
+     CATASTROPHIC LIABILITY FOR DEATH OF THIRD PARTIES                                                 0.00        usd.                                        0.00        usd.
+
+     MEDICAL EXPENSES                                                                                     4,000.00 usd. Per Person
+                                                                                                                                                               9.81        usd.
+                                                                                                         20,000.00 usd. Per Accident
+                                                                                                                      COVERED/EXCLUDED                         PREMIUM
+       LEGAL AID
+                                                                                                                           COVERED                           30.00          usd.
+                                                                                                                      COVERED/EXCLUDED                         PREMIUM
+       AUTOMOBILE ASSISTANCE
+                                                                                                                           COVERED                           30.00          usd.
+
+     The following risks are excluded            Collision, overtuning and glass breakage, fire, total theft and natural disasters, partial theft and vandalism.`);
+
+
+describe("detectPolicyProvider / ANA", () => {
+  it("claims ANA from the letterhead", () => {
+    expect(
+      detectPolicyProvider("A.N.A. COMPAÑIA DE SEGUROS SA DE CV\nwww.anaseguros.com.mx"),
+    ).toBe("ANA");
+  });
+
+  it("does not let GMX's layout rules claim an ANA page", () => {
+    // Both books print "MATERIAL DAMAGE"-ish headings; the brand pass runs
+    // before any layout rule precisely so this can't go the other way.
+    expect(detectPolicyProvider(ANA_AUTO_AMPLIA.text)).toBe("ANA");
+    expect(detectPolicyProvider(ANA_LICENCIA.text)).toBe("ANA");
+  });
+});
+
+describe("parsePolicy / ANA automobile", () => {
+  const p = parsePolicy(ANA_AUTO_AMPLIA);
+
+  it("reads the header band", () => {
+    expect(p.provider).toBe("ANA");
+    expect(p.policyNumber).toBe("700489651");
+    expect(p.insuredName).toBe("RAY DEAN II AND SUSAN ROCKHOLD");
+    expect(p.agentName).toBe("JORGE HUMBERTO CUADROS");
+    expect(p.legalAddress).toBe("10308 DONNA AVE, NORTHRIDGE, CA 91326");
+    expect(p.zip).toBe("91326");
+    expect(p.currency).toBe("USD");
+    expect(p.premiumPayment).toBe("IMMEDIATE");
+  });
+
+  it("reads DD MM YYYY out of the three date column cells", () => {
+    expect(p.policyDate?.toISOString().slice(0, 10)).toBe("2026-08-04");
+    expect(p.policyFrom?.toISOString().slice(0, 10)).toBe("2026-08-07");
+    expect(p.policyTo?.toISOString().slice(0, 10)).toBe("2027-08-07");
+  });
+
+  it("maps the six money cells positionally, not by finding six amounts", () => {
+    // DISCOUNT prints as a bare "-" here. A "take the amounts in order"
+    // reading would shift every value one column left.
+    expect(p.netPremium).toBe(298.61);
+    expect(p.policyFee).toBe(30);
+    expect(p.tax).toBe(26.29);
+    expect(p.total).toBe(354.9);
+  });
+
+  it("reads a TAX that reconciles against the rest of the row", () => {
+    // 298.61 + 30.00 = 328.61, taxed at 8% -> 26.29, totalling 354.90. The
+    // whole row agreeing is what proves the positional mapping landed on the
+    // right cells rather than merely on six numbers.
+    const base = p.netPremium! + p.policyFee!;
+    expect(Math.round(base * 0.08 * 100) / 100).toBe(p.tax);
+    expect(Math.round((base + p.tax!) * 100) / 100).toBe(p.total);
+  });
+
+  it("does not fold LOCAL TAX into the IVA", () => {
+    // It prints 0.00 here, so nothing to fold — but the guard is that a
+    // non-zero one would surface as a note instead of inflating `tax`.
+    expect(p.notes.join(" | ")).not.toMatch(/impuesto local/);
+  });
+
+  it("reads the vehicle by token role, not by column", () => {
+    expect(p.vehicles).toHaveLength(1);
+    expect(p.vehicles[0]).toEqual({
+      item: "VEHICLE",
+      modelYear: "2017",
+      make: "CHRYSLER",
+      bodyType: "PACIFICA",
+      vinNumber: "2C4RC1DG7HR654698",
+      licensePlate: "8BPX206",
+    });
+  });
+
+  it("reads a two-word BODY cell without losing the VIN", () => {
+    // "GENESIS SEDAN" is two tokens where "PACIFICA" is one — the VIN shape
+    // is the anchor, not the token count.
+    const v = parsePolicy(ANA_AUTO_RC_DIAS).vehicles[0];
+    expect(v.make).toBe("FORD");
+    expect(v.vinNumber).toBe("1FBAX2CG3NKA69091");
+    expect(v.licensePlate).toBe("EC46T99");
+  });
+
+  it("skips the empty TRAILER and TOWING slots", () => {
+    // Both print a "." per cell rather than being absent.
+    expect(p.vehicles.map((v) => v.item)).toEqual(["VEHICLE"]);
+  });
+
+  it("records the insured as a named driver with their licence", () => {
+    expect(p.drivers).toHaveLength(1);
+    expect(p.drivers[0].fullName).toBe("RAY DEAN II AND SUSAN ROCKHOLD");
+    expect(p.drivers[0].licenseNumber).toBe("P0066762");
+    expect(p.drivers[0].email).toBe("PROLABSALE@AOL.COM");
+  });
+
+  it("does not read the agent's own street number as the policy number", () => {
+    // "BENITO JUAREZ 25 No.50 INT 38" sits three lines above the No. cell.
+    expect(p.policyNumber).not.toBe("50");
+    expect(p.notes.join(" | ")).not.toMatch(/formas/);
+  });
+
+  it("reads the agent clave without picking up their postal code", () => {
+    // "ROSARITO, BAJA CALIFORNIA 22710" is five digits in the same band.
+    expect(p.notes.join(" | ")).toMatch(/clave de agente: 70175/);
+    expect(p.notes.join(" | ")).not.toMatch(/22710/);
+  });
+
+  it("labels the declared values by their printed item slot", () => {
+    const c = byRisk(p);
+    expect(c["MATERIAL DAMAGE — VEHICLE"]?.insuredAmount).toBe(8000);
+    expect(c["MATERIAL DAMAGE — TRAILER"]?.insuredAmount).toBe(0);
+    expect(c["TOTAL THEFT — TOWING"]?.insuredAmount).toBe(0);
+  });
+
+  it("keeps the deductible sentence out of the value columns", () => {
+    const c = byRisk(p);
+    expect(c["MATERIAL DAMAGE — VEHICLE"]?.deductible).toBe(
+      "WITH MINIMUM OF $500.00 ON AUTOS (SEDANS, COUPES, CONVERTIBLES AND " +
+        "STATION WAGONS) AND $500.00 ON ALL OTHERS (PICK UPS, VANS, SUV´s AND " +
+        "MOTOR HOMES).",
+    );
+  });
+
+  it("does not mistake the $500.00 inside the deductible for a sum insured", () => {
+    // It is the one amount in the block not suffixed "DLLS.".
+    const amounts = p.coverages.map((c) => c.insuredAmount);
+    expect(amounts).not.toContain(500);
+  });
+
+  it("splits the per-person and per-accident limits", () => {
+    const c = byRisk(p);
+    expect(c["BODILY INJURY LIABILITY — POR PERSONA"]?.insuredAmount).toBe(100000);
+    expect(c["BODILY INJURY LIABILITY — POR EVENTO"]?.insuredAmount).toBe(200000);
+    expect(c["MEDICAL EXPENSES — POR PERSONA"]?.insuredAmount).toBe(5000);
+    expect(c["MEDICAL EXPENSES — POR EVENTO"]?.insuredAmount).toBe(25000);
+  });
+
+  it("records an add-on's figure as a premium, never as a sum insured", () => {
+    // $40 is what legal aid COST. As `insuredAmount` it would read on the
+    // review screen as a $40 liability limit.
+    const c = byRisk(p);
+    expect(c["LEGAL AID"]?.premium).toBe(40);
+    expect(c["LEGAL AID"]?.insuredAmount).toBeNull();
+    expect(c["ROADSIDE ASSISTANCE"]?.premium).toBe(40);
+  });
+
+  it("unpacks section 9's parenthesised limit and deductible", () => {
+    const c = byRisk(p);
+    const theft = c["ELITE / ELITE PLUS — PARTIAL THEFT: EXCLUDED"];
+    expect(theft?.insuredAmount).toBe(0);
+    expect(theft?.deductible).toBe("0.00 DLLS. POR EVENTO");
+    expect(c["ELITE / ELITE PLUS — VANDALISM: EXCLUDED"]).toBeDefined();
+  });
+
+  it("emits each coverage once even though the PDF prints the face twice", () => {
+    // The real upload is ORIGINAL + AGENT COPY + receipt + three travel
+    // cards, all concatenated into one string before parsing.
+    const doubled = page(ANA_AUTO_AMPLIA.text + "\n\n" + ANA_AUTO_AMPLIA.text);
+    expect(parsePolicy(doubled).coverages).toHaveLength(p.coverages.length);
+    expect(parsePolicy(doubled).vehicles).toHaveLength(1);
+  });
+});
+
+describe("policy type, as a name for confirm to resolve", () => {
+  it("names ANA's two faces after the legacy tables they belong to", () => {
+    expect(parsePolicy(ANA_AUTO_AMPLIA).policyTypeName).toBe("AUTO");
+    expect(parsePolicy(ANA_AUTO_RC_DIAS).policyTypeName).toBe("AUTO");
+    expect(parsePolicy(ANA_LICENCIA).policyTypeName).toBe("LICENCIAS");
+  });
+
+  it("emits a NAME, never an id — the parser must not need a database", () => {
+    // Anything id-shaped here would mean the parser had reached for the DB.
+    for (const p of [ANA_AUTO_AMPLIA, ANA_AUTO_RC_DIAS, ANA_LICENCIA]) {
+      expect(parsePolicy(p).policyTypeName).toMatch(/^[A-Z_]+$/);
+    }
+  });
+
+  it("leaves the type unnamed when no parser claimed the page", () => {
+    expect(parsePolicy(page("a laundry receipt")).policyTypeName).toBeNull();
+  });
+});
+
+describe("parsePolicy / ANA responsabilidad civil por días", () => {
+  const p = parsePolicy(ANA_AUTO_RC_DIAS);
+
+  it("reads a by-the-day term rather than defaulting to a year", () => {
+    // Left at the schema's 365 default this weekend policy would sit in the
+    // renewals window a year out.
+    expect(p.policyFrom?.toISOString().slice(0, 10)).toBe("2026-07-23");
+    expect(p.policyTo?.toISOString().slice(0, 10)).toBe("2026-07-26");
+    expect(p.coveragePeriodDays).toBe(3);
+  });
+
+  it("reads the clave when the agent's phone occupies the left cell", () => {
+    // The by-the-day products print "(661) 612 12 55" ahead of the clave, so
+    // it is no longer the first thing on its line.
+    expect(p.notes.join(" | ")).toMatch(/clave de agente: 70175/);
+  });
+
+  it("marks the excluded sections as excluded, not as insured for zero", () => {
+    const risks = p.coverages.map((c) => c.risk);
+    expect(risks).toContain("MATERIAL DAMAGE — VEHICLE: EXCLUDED");
+    expect(risks).toContain("TOTAL THEFT — TOWING: EXCLUDED");
+    // The liability sections are what this product actually sells, and they
+    // are NOT excluded.
+    expect(risks).toContain("LIABILITY FOR PROPERTY DAMAGE TO THIRD PARTIES");
+  });
+});
+
+describe("parsePolicy / ANA driver's policy (licencia)", () => {
+  const p = parsePolicy(ANA_LICENCIA);
+
+  it("reads the holder off the numbered POLICY HOLDER list", () => {
+    expect(p.policyNumber).toBe("700489616");
+    expect(p.insuredName).toBe("PAMELA DENISE WAGONER");
+    expect(p.legalAddress).toBe("49305 HIGHWAY 74 SPC 10, PALM DESERT, CA, 92260");
+    expect(p.zip).toBe("92260");
+  });
+
+  it("lists one driver, not one per printed copy of the page", () => {
+    // The face renders three times in the real PDF; an unbounded walk
+    // returns the same person three times, which reads as a three-driver
+    // policy rather than as a parse bug.
+    const tripled = page([ANA_LICENCIA.text, ANA_LICENCIA.text, ANA_LICENCIA.text].join("\n\n"));
+    expect(p.drivers).toHaveLength(1);
+    expect(parsePolicy(tripled).drivers).toHaveLength(1);
+  });
+
+  it("splits the phone off the name even without the printed column gap", () => {
+    // The phone shares the name cell, and the only thing marking it off is
+    // white space — which the OCR seam is free to collapse. Depending on the
+    // gap surviving is what put "PAMELA DENISE WAGONER Ph.3102001538" in the
+    // insured field, where it matched no customer.
+    const collapsed = page(ANA_LICENCIA.text.replace(/ {2,}/g, " "));
+    expect(parsePolicy(collapsed).insuredName).toBe("PAMELA DENISE WAGONER");
+  });
+
+  it("drops the four empty driver slots", () => {
+    // Slots 2-5 print an empty NAME and a bare "NONE" licence.
+    expect(p.drivers.map((d) => d.fullName)).toEqual(["PAMELA DENISE WAGONER"]);
+    expect(p.drivers[0].licenseNumber).toBe("N0017668");
+    expect(p.drivers[0].phone).toBe("3102001538");
+  });
+
+  it("insures no vehicle", () => {
+    expect(p.vehicles).toEqual([]);
+    expect(p.notes.join(" | ")).toMatch(/no ampara un veh[íi]culo determinado/);
+  });
+
+  it("separates the SUM INSURED and PREMIUM columns by position", () => {
+    // Both columns print the same shape ("100,000.00 usd." / "18.70 usd.")
+    // and neither is labelled per row — only the offset tells them apart.
+    const c = byRisk(p);
+    const pd = c["LIABILITY FOR PROPERTY DAMAGE TO THIRD PARTIES"];
+    expect(pd?.insuredAmount).toBe(100000);
+    expect(pd?.premium).toBe(18.7);
+  });
+
+  it("reads the trailing Per Person / Per Accident labels on this layout", () => {
+    // They FOLLOW their amount here and PRECEDE it on the automobile face.
+    const c = byRisk(p);
+    expect(c["BODILY INJURY LIABILITY — POR PERSONA"]?.insuredAmount).toBe(100000);
+    expect(c["BODILY INJURY LIABILITY — POR EVENTO"]?.insuredAmount).toBe(200000);
+    expect(c["MEDICAL EXPENSES — POR PERSONA"]?.insuredAmount).toBe(4000);
+    expect(c["MEDICAL EXPENSES — POR EVENTO"]?.insuredAmount).toBe(20000);
+  });
+
+  it("charges a section's premium once, not once per limit", () => {
+    const c = byRisk(p);
+    expect(c["BODILY INJURY LIABILITY — POR PERSONA"]?.premium).toBe(54.27);
+    expect(c["BODILY INJURY LIABILITY — POR EVENTO"]?.premium).toBeNull();
+  });
+
+  it("handles the section order this layout uses", () => {
+    // CATASTROPHIC LIABILITY prints ABOVE MEDICAL EXPENSES here and below it
+    // on the automobile face; blocks are keyed by where the labels land.
+    const c = byRisk(p);
+    expect(c["CATASTROPHIC LIABILITY FOR DEATH OF THIRD PARTIES"]?.insuredAmount).toBe(0);
+    expect(c["LEGAL AID"]?.premium).toBe(30);
+    expect(c["ROADSIDE ASSISTANCE"]?.premium).toBe(30);
+  });
+
+  it("carries the excluded-risk sentence that defines the product", () => {
+    expect(p.notes.join(" | ")).toMatch(/riesgos excluidos: Collision, overtuning/);
+  });
+});

apps/api/src/policy-ocr/policy-matcher.service.spec.ts

@@ -0,0 +1,100 @@
+import { PolicyMatcherService } from "./policy-matcher.service";
+import type { PrismaService } from "../prisma/prisma.service";
+import type { ParsedPolicy } from "./parsers/policy-parser";
+
+function parsed(over: Partial<ParsedPolicy> = {}): ParsedPolicy {
+  return {
+    provider: "GMX",
+    policyNumber: null,
+    insuredName: null,
+    notes: [],
+    coverages: [],
+    vehicles: [],
+    drivers: [],
+    ...over,
+  } as unknown as ParsedPolicy;
+}
+
+function prismaStub(policies: unknown[], customers: { id: string; name: string }[]) {
+  const findManyPolicy = jest.fn().mockResolvedValue(policies);
+  const findManyCustomer = jest.fn().mockResolvedValue(customers);
+  return {
+    prisma: {
+      policy: { findMany: findManyPolicy },
+      customer: { findMany: findManyCustomer },
+    } as unknown as PrismaService,
+    findManyPolicy,
+    findManyCustomer,
+  };
+}
+
+const BOOK = [
+  { id: "cust-1", name: "WAGONER, PAMELA" },
+  { id: "cust-2", name: "SMITH, JOHN" },
+];
+
+describe("PolicyMatcherService name suggestions", () => {
+  it("suggests a customer when the policy number is new", async () => {
+    const { prisma } = prismaStub([], BOOK);
+    const svc = new PolicyMatcherService(prisma);
+
+    const r = await svc.match(
+      parsed({ policyNumber: "P-999", insuredName: "PAMELA DENISE WAGONER" } as never),
+    );
+
+    expect(r.customerSuggestions).toEqual([
+      expect.objectContaining({ customerId: "cust-1", tier: "PARTIAL" }),
+    ]);
+    // The suggestion is surfaced, never applied.
+    expect(r.customerId).toBeNull();
+    expect(r.confident).toBe(false);
+    expect(r.note).toContain("posibles clientes por nombre: WAGONER, PAMELA");
+  });
+
+  it("suggests when the policy number could not be read at all", async () => {
+    const { prisma } = prismaStub([], BOOK);
+    const svc = new PolicyMatcherService(prisma);
+
+    const r = await svc.match(parsed({ insuredName: "PAMELA WAGONER" } as never));
+
+    expect(r.customerSuggestions[0]).toMatchObject({ customerId: "cust-1", tier: "EXACT" });
+    expect(r.customerId).toBeNull();
+    expect(r.note).toBe(
+      "no se pudo leer el número de póliza; posible cliente por nombre: WAGONER, PAMELA",
+    );
+  });
+
+  it("does not touch the book when the policy number hits", async () => {
+    const { prisma, findManyCustomer } = prismaStub(
+      [
+        {
+          id: "pol-1",
+          policyNumber: "P-1",
+          customerId: "cust-2",
+          customer: { name: "SMITH, JOHN" },
+        },
+      ],
+      BOOK,
+    );
+    const svc = new PolicyMatcherService(prisma);
+
+    const r = await svc.match(
+      parsed({ policyNumber: "P-1", insuredName: "PAMELA WAGONER" } as never),
+    );
+
+    expect(r.confident).toBe(true);
+    expect(r.customerId).toBe("cust-2");
+    expect(r.customerSuggestions).toEqual([]);
+    expect(findManyCustomer).not.toHaveBeenCalled();
+  });
+
+  it("reads the customer book once across a batch", async () => {
+    const { prisma, findManyCustomer } = prismaStub([], BOOK);
+    const svc = new PolicyMatcherService(prisma);
+
+    await svc.match(parsed({ policyNumber: "A", insuredName: "PAMELA WAGONER" } as never));
+    await svc.match(parsed({ policyNumber: "B", insuredName: "JOHN SMITH" } as never));
+
+    expect(findManyCustomer).toHaveBeenCalledTimes(1);
+  });
+});

apps/api/src/policy-ocr/policy-matcher.service.ts

@@ -1,6 +1,12 @@
 import { Injectable } from "@nestjs/common";
 import { PrismaService } from "../prisma/prisma.service";
 import type { ParsedPolicy } from "./parsers/policy-parser";
+import {
+  suggestCustomersByName,
+  suggestionNote,
+  type CustomerNameRow,
+  type CustomerNameSuggestion,
+} from "./name-matcher";
 
 export interface MatchResult {
   policyId: string | null;
@@ -14,8 +20,24 @@ export interface MatchResult {
    * the policy number is shared across customers and a human must pick.
    */
   candidates: { policyId: string; customerId: string; customerName: string; policyNumber: string }[];
+  /**
+   * Customers whose name resembles the printed insured name. Populated only
+   * when the policy number resolved to nothing, and never used to set
+   * `customerId` or `confident` — see the class comment.
+   */
+  customerSuggestions: CustomerNameSuggestion[];
 }
 
+/**
+ * How long the customer book is reused across documents in a batch.
+ *
+ * A twenty-page batch would otherwise read all 1536 rows twenty times. The
+ * only cost of the staleness is that a customer created in the last minute
+ * is not suggested — the picker still finds them, so nothing is lost that a
+ * reviewer cannot do in one click.
+ */
+const BOOK_TTL_MS = 60_000;
+
 /**
  * Resolves a parsed policy page to an existing Policy (and its customer) the
  * office already holds.
@@ -33,14 +55,29 @@ export interface MatchResult {
  * policy numbers across customers do occur (same group policy bound by two
  * related parties), and picking one arbitrarily would silently book the
  * wrong coverage.
+ *
+ * On that zero-hit path only, the printed name is used to *rank the picker*
+ * — see `name-matcher.ts`. That is not a walk-back of the rule above: the
+ * suggestion never reaches `customerId` or `confident`, a human still picks,
+ * and the ranking exists because the office writes names surname-first
+ * ("WAGONER, PAMELA") while carriers print them given-name-first ("PAMELA
+ * DENISE WAGONER"), so the reviewer is retyping a name the machine could
+ * have offered.
  */
 @Injectable()
 export class PolicyMatcherService {
+  private book: { rows: CustomerNameRow[]; loadedAt: number } | null = null;
+
   constructor(private readonly prisma: PrismaService) {}
 
   async match(parsed: ParsedPolicy): Promise<MatchResult> {
     if (!parsed.policyNumber) {
-      return this.unmatched("no se pudo leer el número de póliza");
+      // No number to search on, so the page goes to review with a picker —
+      // the same place the name suggestions help.
+      return this.unmatched(
+        "no se pudo leer el número de póliza",
+        await this.suggestByName(parsed.insuredName),
+      );
     }
 
     const rows = await this.prisma.policy.findMany({
@@ -61,22 +98,33 @@ export class PolicyMatcherService {
     }));
 
     if (rows.length === 0) {
+      const suggestions = await this.suggestByName(parsed.insuredName);
+      const hint = suggestionNote(suggestions);
       return {
         policyId: null,
         customerId: null,
-        note: `no se encontró ninguna póliza con el número ${parsed.policyNumber}`,
+        note: [
+          `no se encontró ninguna póliza con el número ${parsed.policyNumber}`,
+          hint,
+        ]
+          .filter(Boolean)
+          .join("; "),
         confident: false,
         candidates: [],
+        customerSuggestions: suggestions,
       };
     }
 
     if (rows.length > 1) {
+      // The policy number did find rows; the reviewer picks among those, and
+      // adding name guesses on top would only add noise.
       return {
         policyId: null,
         customerId: null,
         note: `${rows.length} pólizas comparten el número ${parsed.policyNumber}`,
         confident: false,
         candidates,
+        customerSuggestions: [],
       };
     }
 
@@ -86,16 +134,47 @@ export class PolicyMatcherService {
       note: `coincidencia exacta por número de póliza ${parsed.policyNumber}`,
       confident: true,
       candidates,
+      customerSuggestions: [],
     };
   }
 
-  private unmatched(note: string): MatchResult {
+  private async suggestByName(
+    insuredName: string | null | undefined,
+  ): Promise<CustomerNameSuggestion[]> {
+    if (!insuredName) return [];
+    return suggestCustomersByName(insuredName, await this.customerBook());
+  }
+
+  /**
+   * The whole customer book, held briefly. 1536 rows of `{id, name}` is a
+   * few hundred kilobytes and the comparison is pure token-set work, so
+   * scanning it beats any SQL approximation — and a `LIKE` search would in
+   * any case have to guess which token is the surname, which is the one
+   * thing the office's own data does not agree on.
+   */
+  private async customerBook(): Promise<CustomerNameRow[]> {
+    if (this.book && Date.now() - this.book.loadedAt < BOOK_TTL_MS) {
+      return this.book.rows;
+    }
+    const rows = await this.prisma.customer.findMany({
+      select: { id: true, name: true },
+    });
+    this.book = { rows, loadedAt: Date.now() };
+    return rows;
+  }
+
+  private unmatched(
+    note: string,
+    customerSuggestions: CustomerNameSuggestion[] = [],
+  ): MatchResult {
+    const hint = suggestionNote(customerSuggestions);
     return {
       policyId: null,
       customerId: null,
-      note,
+      note: [note, hint].filter(Boolean).join("; "),
       confident: false,
       candidates: [],
+      customerSuggestions,
     };
   }
 }

apps/api/src/policy-ocr/policy-ocr.dto.ts

@@ -3,10 +3,13 @@ import {
   IsArray,
   IsDateString,
   IsEnum,
+  IsInt,
   IsNumber,
   IsObject,
   IsOptional,
   IsString,
+  Max,
+  Min,
   MinLength,
   ValidateNested,
 } from "class-validator";
@@ -19,6 +22,11 @@ export class ConfirmPolicyDocumentDto {
 
   /** Required when creating a new Policy; ignored if `policyId` is set. */
   @IsOptional() @IsString() customerId?: string;
+  /** Reviewer's explicit lookup picks. Both beat the parsed name; omitted,
+   *  the service resolves `policy_types` / `insurance_providers` by name and
+   *  leaves the FK null when there is no such row. */
+  @IsOptional() @IsString() policyTypeId?: string;
+  @IsOptional() @IsString() insuranceProviderId?: string;
   /** Set when the document matched an existing Policy. */
   @IsOptional() @IsString() policyId?: string;
 
@@ -35,8 +43,12 @@ export class ConfirmPolicyDocumentDto {
   @IsOptional() @IsNumber() netPremium?: number;
   @IsOptional() @IsNumber() policyFee?: number;
   @IsOptional() @IsNumber() brokerFee?: number;
+  @IsOptional() @IsNumber() tax?: number;
   @IsOptional() @IsNumber() total?: number;
   @IsOptional() @IsString() premiumPayment?: string;
+  /** Printed term in days. Omitted leaves the parsed value (or the schema's
+   *  365 default) in place; ANA sells 3- and 4-day tourist policies. */
+  @IsOptional() @IsInt() @Min(1) @Max(3660) coveragePeriodDays?: number;
   /** Coverages parsed off the PDF, passed through verbatim to Policy.coveragesJson. */
   @IsOptional() @IsObject() coveragesJson?: unknown;
 
@@ -68,8 +80,10 @@ export class ReviewPolicyDocumentDto {
   @IsOptional() @IsNumber() netPremium?: number;
   @IsOptional() @IsNumber() policyFee?: number;
   @IsOptional() @IsNumber() brokerFee?: number;
+  @IsOptional() @IsNumber() tax?: number;
   @IsOptional() @IsNumber() total?: number;
   @IsOptional() @IsString() premiumPayment?: string;
+  @IsOptional() @IsInt() @Min(1) @Max(3660) coveragePeriodDays?: number;
   @IsOptional() @IsObject() coveragesJson?: unknown;
 
   /** Set by the reviewer when the document matched an existing Policy. */

apps/api/src/policy-ocr/policy-ocr.service.ts

@@ -10,7 +10,7 @@ import { PrismaService } from "../prisma/prisma.service";
 import { StorageService } from "../storage/storage.service";
 import type { UploadedFileLike } from "../storage/upload-file";
 import { OCR_PROVIDER, type OcrPage, type OcrProvider } from "../statements/ocr/ocr.provider";
-import { parsePolicy } from "./parsers/policy-parser";
+import { parsePolicy, type ParsedDriver, type ParsedVehicle } from "./parsers/policy-parser";
 import { PolicyMatcherService } from "./policy-matcher.service";
 import type {
   ConfirmPolicyBatchDto,
@@ -69,8 +69,11 @@ export class PolicyOcrService {
       );
     }
 
+    // The provider is not asked of the uploader and not assumed: `process`
+    // sets it from what the parsers actually claimed, so the batch label can
+    // never contradict its own documents. Until then it says so.
     const batch = await this.prisma.policyOcrBatch.create({
-      data: { provider: "GMX", uploadedById, label, fileCount: files.length },
+      data: { provider: "por detectar", uploadedById, label, fileCount: files.length },
     });
 
     const copies = files.map((f) => ({ buffer: f.buffer, name: f.originalname }));
@@ -112,6 +115,7 @@ export class PolicyOcrService {
 
     let fileOrdinal = 0;
     let globalPageOrdinal = 0;
+    const providersSeen = new Set<string>();
     for (const file of files) {
       fileOrdinal += 1;
       const sourceKey = `policy-ocr/${batchId}/source-${fileOrdinal}.pdf`;
@@ -155,6 +159,7 @@ export class PolicyOcrService {
         if (parsed.provider === "") {
           throw new Error("no se reconoció el proveedor");
         }
+        providersSeen.add(parsed.provider);
         const match = await this.matcher.match(parsed);
         const notes = [...parsed.notes, match.note].filter(Boolean);
         // Confident when exactly one Policy carries the printed number —
@@ -187,18 +192,31 @@ export class PolicyOcrService {
               parsed.policyFee != null ? new Prisma.Decimal(parsed.policyFee) : null,
             extractedBrokerFee:
               parsed.brokerFee != null ? new Prisma.Decimal(parsed.brokerFee) : null,
+            extractedTax:
+              parsed.tax != null ? new Prisma.Decimal(parsed.tax) : null,
             extractedTotal:
               parsed.total != null ? new Prisma.Decimal(parsed.total) : null,
             extractedCoveragesJson: parsed.coverages.length
               ? (parsed.coverages as unknown as Prisma.InputJsonValue)
               : Prisma.DbNull,
             extractedPremiumPayment: parsed.premiumPayment,
+            extractedCoveragePeriodDays: parsed.coveragePeriodDays,
+            extractedVehiclesJson: parsed.vehicles.length
+              ? (parsed.vehicles as unknown as Prisma.InputJsonValue)
+              : Prisma.DbNull,
+            extractedDriversJson: parsed.drivers.length
+              ? (parsed.drivers as unknown as Prisma.InputJsonValue)
+              : Prisma.DbNull,
+            extractedPolicyTypeName: parsed.policyTypeName,
             matchedPolicyId: match.policyId,
             matchedCustomerId: match.customerId,
             matchCandidates: match.candidates.length
               ? (match.candidates as unknown as Prisma.InputJsonValue)
               : Prisma.DbNull,
-            matchNote: notes.join("; ").slice(0, 190),
+            customerSuggestions: match.customerSuggestions.length
+              ? (match.customerSuggestions as unknown as Prisma.InputJsonValue)
+              : Prisma.DbNull,
+            matchNote: notes.join("; "),
           },
         });
       } catch (err) {
@@ -211,7 +229,7 @@ export class PolicyOcrService {
             pageNumber: fileOrdinal,
             storageKey: sourceKey,
             status: "OCR_FAILED",
-            matchNote: (err as Error).message.slice(0, 190),
+            matchNote: (err as Error).message,
           },
         });
       }
@@ -219,7 +237,13 @@ export class PolicyOcrService {
 
     await this.prisma.policyOcrBatch.update({
       where: { id: batchId },
-      data: { status: "READY_FOR_REVIEW" },
+      data: {
+        status: "READY_FOR_REVIEW",
+        // Whatever the parsers claimed. A mixed upload is labelled as mixed
+        // rather than as whichever provider happened to come first — the
+        // review header is the only place staff see what they dropped in.
+        provider: [...providersSeen].sort().join(" + ") || "desconocido",
+      },
     });
   }
 
@@ -343,12 +367,14 @@ export class PolicyOcrService {
           dto.policyFee != null ? new Prisma.Decimal(dto.policyFee) : undefined,
         extractedBrokerFee:
           dto.brokerFee != null ? new Prisma.Decimal(dto.brokerFee) : undefined,
+        extractedTax: dto.tax != null ? new Prisma.Decimal(dto.tax) : undefined,
         extractedTotal:
           dto.total != null ? new Prisma.Decimal(dto.total) : undefined,
         extractedCoveragesJson: dto.coveragesJson
           ? (dto.coveragesJson as Prisma.InputJsonValue)
           : undefined,
         extractedPremiumPayment: dto.premiumPayment ?? undefined,
+        extractedCoveragePeriodDays: dto.coveragePeriodDays ?? undefined,
         matchedPolicyId,
         matchedCustomerId,
         status: dto.forceConfirm ? "CONFIRMED" : "MATCHED",
@@ -447,14 +473,18 @@ export class PolicyOcrService {
         );
       }
 
-      // 1. Resolve target Policy (create or update). Field selection: every
+      // 1. Resolve the lookup rows the parser can only name. The reviewer's
+      // explicit pick always wins; the parsed name is the fallback.
+      const lookups = await this.resolveLookups(item, doc);
+
+      // 2. Resolve target Policy (create or update). Field selection: every
       // non-null `extracted*` on the doc (post-review) is written. Null is
       // preserved — never overwrite an existing Policy's `netPremium` with
       // null because the certificate page didn't carry one.
       let policyId = item.policyId ?? null;
 
       if (policyId) {
-        const updateData = buildPolicyUpdateFromDoc(item, doc);
+        const updateData = buildPolicyUpdateFromDoc(item, doc, lookups);
         await this.prisma.policy.update({
           where: { id: policyId },
           data: updateData,
@@ -467,21 +497,25 @@ export class PolicyOcrService {
             `Documento página ${doc.pageNumber}: falta número de póliza.`,
           );
         }
-        const createData = buildPolicyCreateFromDoc(item, doc, item.customerId!);
+        const createData = buildPolicyCreateFromDoc(item, doc, item.customerId!, lookups);
         const created = await this.prisma.policy.create({
           data: createData,
         });
         policyId = created.id;
       }
 
-      // 2. Attach the source PDF as a PolicyDocument. `doc.storageKey`
+      // 3. Vehicles and named drivers, for the providers whose face carries
+      // them (ANA's automobile and driver's policies; never GMX Hogar).
+      await this.applyVehiclesAndDrivers(doc, policyId);
+
+      // 4. Attach the source PDF as a PolicyDocument. `doc.storageKey`
       // already points at the exact upload (`policy-ocr/{batchId}/source-N.pdf`)
       // so the attach is just a stream copy into the policy's namespace —
       // the previous per-page "which file did this page come from" walk is
       // gone because one PDF = one doc now.
-      await this.attachSourcePdf(doc.storageKey, policyId);
+      await this.attachSourcePdf(doc.storageKey, policyId, doc.provider);
 
-      // 3. Optionally post the premium to the ledger. Only when staff
+      // 5. Optionally post the premium to the ledger. Only when staff
       // explicitly asked (`postPremium` true) and netPremium parses — without
       // that gate a missing premium would silently book $0.
       let postedTransactionId: string | null = null;
@@ -539,13 +573,149 @@ export class PolicyOcrService {
     };
   }
 
+  /**
+   * Turn the two things the parser can only NAME into foreign keys.
+   *
+   * The parser is a pure function over text and never touches the database,
+   * so it emits `policyTypeName` ("AUTO") and `provider` ("ANA"). Resolving
+   * them here keeps that boundary and means a renamed lookup row is a data
+   * change rather than a parser change.
+   *
+   * **Resolve, never create.** A missing `policy_types` row is a signal that
+   * a human deleted it (that is exactly how M_EMPR disappeared), and silently
+   * recreating it would undo that decision with no record. The field stays
+   * null and the reviewer can add the row through the lookups screen.
+   *
+   * An explicit pick from the reviewer always beats the parsed name.
+   */
+  private async resolveLookups(
+    item: ConfirmPolicyDocumentDto,
+    doc: { extractedPolicyTypeName: string | null; provider: string | null },
+  ): Promise<{ policyTypeId?: string; insuranceProviderId?: string }> {
+    const out: { policyTypeId?: string; insuranceProviderId?: string } = {};
+
+    if (item.policyTypeId) {
+      out.policyTypeId = item.policyTypeId;
+    } else if (doc.extractedPolicyTypeName) {
+      const row = await this.prisma.policyType.findUnique({
+        where: { name: doc.extractedPolicyTypeName },
+        select: { id: true },
+      });
+      if (row) out.policyTypeId = row.id;
+    }
+
+    if (item.insuranceProviderId) {
+      out.insuranceProviderId = item.insuranceProviderId;
+    } else if (doc.provider) {
+      const name = PROVIDER_ROW_NAME[doc.provider] ?? doc.provider;
+      const row = await this.prisma.insuranceProvider.findFirst({
+        where: { name },
+        select: { id: true },
+      });
+      if (row) out.insuranceProviderId = row.id;
+    }
+
+    return out;
+  }
+
+  /**
+   * Write the parsed `Vehicle` and `InsuredDriver` rows onto the policy.
+   *
+   * Both inserts are skipped when an equivalent row is already on the policy.
+   * The reason is `confirmBatch` applying to an EXISTING policy: the office
+   * uploads a renewal for a car already on file, and a blind insert would
+   * leave the customer with the same VIN listed twice with no way to tell
+   * which row the renewal belongs to. Matching is on the identifier the
+   * document actually prints — the VIN for a vehicle (falling back to the
+   * plate, since ANA's TRAILER/TOWING slots have no VIN), the licence number
+   * for a driver (falling back to the name).
+   *
+   * Nothing is ever updated or deleted here. A vehicle whose plate changed
+   * lands as a second row for a human to reconcile, which is the safe half
+   * of the mistake: an over-write would destroy the only record of what was
+   * insured last term.
+   */
+  private async applyVehiclesAndDrivers(
+    doc: { extractedVehiclesJson: Prisma.JsonValue | null; extractedDriversJson: Prisma.JsonValue | null },
+    policyId: string,
+  ): Promise<void> {
+    const vehicles = asArray<ParsedVehicle>(doc.extractedVehiclesJson);
+    const drivers = asArray<ParsedDriver>(doc.extractedDriversJson);
+    if (vehicles.length === 0 && drivers.length === 0) return;
+
+    const policy = await this.prisma.policy.findUnique({
+      where: { id: policyId },
+      select: { customerId: true },
+    });
+    if (!policy) return;
+
+    if (vehicles.length) {
+      const existing = await this.prisma.vehicle.findMany({
+        where: { policyId },
+        select: { vinNumber: true, licensePlate: true },
+      });
+      const seen = new Set(
+        existing.flatMap((v) =>
+          [v.vinNumber, v.licensePlate].filter((k): k is string => !!k).map(norm),
+        ),
+      );
+      for (const v of vehicles) {
+        const key = norm(v.vinNumber ?? v.licensePlate ?? "");
+        if (!key || seen.has(key)) continue;
+        seen.add(key);
+        await this.prisma.vehicle.create({
+          data: {
+            policyId,
+            customerId: policy.customerId,
+            make: v.make,
+            // ANA prints one BODY cell, not separate model/body columns, so
+            // it lands on `bodyType`; `model` stays null rather than being
+            // guessed out of the same string.
+            bodyType: v.bodyType,
+            modelYear: v.modelYear,
+            vinNumber: v.vinNumber,
+            licensePlate: v.licensePlate,
+            // "VEHICLE" / "TRAILER" / "TOWING" — the printed slot, which is
+            // the difference between the insured car and the trailer behind
+            // it and has no column of its own.
+            notes: v.item && v.item !== "VEHICLE" ? v.item : null,
+          },
+        });
+      }
+    }
+
+    if (drivers.length) {
+      const existing = await this.prisma.insuredDriver.findMany({
+        where: { policyId },
+        select: { licenseNumber: true, fullName: true },
+      });
+      const seen = new Set(
+        existing.flatMap((d) =>
+          [d.licenseNumber, d.fullName].filter((k): k is string => !!k).map(norm),
+        ),
+      );
+      for (const d of drivers) {
+        const key = norm(d.licenseNumber ?? d.fullName ?? "");
+        if (!key || seen.has(key)) continue;
+        seen.add(key);
+        await this.prisma.insuredDriver.create({
+          data: { policyId, fullName: d.fullName, licenseNumber: d.licenseNumber },
+        });
+      }
+    }
+  }
+
   /**
    * Stream the source PDF (`sourceKey`, set by `process` on the doc row)
    * into the policy's storage namespace and create a `PolicyDocument`
    * pointer. Trivial now that the doc row holds the exact source key —
    * the old per-page "which file did this page come from" walk is gone.
    */
-  private async attachSourcePdf(sourceKey: string, policyId: string): Promise<void> {
+  private async attachSourcePdf(
+    sourceKey: string,
+    policyId: string,
+    provider: string | null,
+  ): Promise<void> {
     const got = await this.storage.getStream(sourceKey);
     const chunks: Buffer[] = [];
     for await (const c of got.stream) chunks.push(c as Buffer);
@@ -556,7 +726,10 @@ export class PolicyOcrService {
     await this.prisma.policyDocument.create({
       data: {
         policyId,
-        documentType: "GMX_POLICY",
+        // Named after whichever parser claimed the page. Was hardcoded
+        // `GMX_POLICY`, which mislabelled every ANA upload as a GMX
+        // document in the policy's file list.
+        documentType: `${provider ?? "OCR"}_POLICY`,
         storageKey: newKey,
       },
     });
@@ -588,6 +761,27 @@ export class PolicyOcrService {
   }
 }
 
+/**
+ * The parser's provider code is not the carrier's row name in
+ * `insurance_providers`, and the two namespaces are allowed to differ.
+ *
+ * ANA is the case that forces this: the office's book is filed under
+ * "ANA SEGUROS" (738 policies). A bare "ANA" row also existed with 1 policy
+ * and is merged away by `20260815160000_policy_type_repair`, so an exact-name
+ * lookup on the parser's "ANA" would find nothing at all after that migration.
+ *
+ * Anything not listed resolves by its own name.
+ */
+const PROVIDER_ROW_NAME: Record<string, string> = {
+  ANA: "ANA SEGUROS",
+};
+
+/** The lookup FKs resolved for one document, absent when unresolvable. */
+interface ResolvedLookups {
+  policyTypeId?: string;
+  insuranceProviderId?: string;
+}
+
 /** Map a (post-review) doc + final confirmed fields onto a `Policy.update`
  *  payload. Every field that is null in both inputs is omitted so we never
  *  write null over a value the Policy already carries (the GMX certificate
@@ -608,10 +802,13 @@ function buildPolicyUpdateFromDoc(
     extractedNetPremium: Prisma.Decimal | null;
     extractedPolicyFee: Prisma.Decimal | null;
     extractedBrokerFee: Prisma.Decimal | null;
+    extractedTax: Prisma.Decimal | null;
     extractedTotal: Prisma.Decimal | null;
     extractedCoveragesJson: Prisma.JsonValue | null;
     extractedPremiumPayment: string | null;
+    extractedCoveragePeriodDays: number | null;
   },
+  lookups: ResolvedLookups,
 ): Prisma.PolicyUpdateInput {
   const numOrUndef = (a: number | undefined, b: Prisma.Decimal | null): Prisma.Decimal | undefined => {
     if (a != null) return new Prisma.Decimal(a);
@@ -631,14 +828,31 @@ function buildPolicyUpdateFromDoc(
 
   return {
     policyNumber: strOrUndef(item.policyNumber, doc.extractedPolicyNumber),
+    // `connect` rather than a raw id: this is the CHECKED update input. Left
+    // undefined when unresolved, so an existing Policy never loses a type or
+    // carrier it already had because this document could not name one.
+    policyType: lookups.policyTypeId ? { connect: { id: lookups.policyTypeId } } : undefined,
+    insuranceProvider: lookups.insuranceProviderId
+      ? { connect: { id: lookups.insuranceProviderId } }
+      : undefined,
     agentName: strOrUndef(item.agentName, doc.extractedAgentName),
     policyFrom: dateOrUndef(item.policyFrom, doc.extractedPolicyFrom),
     policyTo: dateOrUndef(item.policyTo, doc.extractedPolicyTo),
     policyDate: dateOrUndef(item.policyDate, doc.extractedPolicyDate),
+    // Left undefined when the document didn't print a term, so the schema
+    // default (365) stands for GMX. ANA's by-the-day policies DO print one,
+    // and the default would otherwise turn a 4-day tourist policy into an
+    // annual one on the renewals screen.
+    coveragePeriodDays:
+      item.coveragePeriodDays ?? doc.extractedCoveragePeriodDays ?? undefined,
     currency: strOrUndef(item.currency, doc.extractedCurrency) as Currency | undefined,
     netPremium: numOrUndef(item.netPremium, doc.extractedNetPremium),
     policyFee: numOrUndef(item.policyFee, doc.extractedPolicyFee),
     brokerFee: numOrUndef(item.brokerFee, doc.extractedBrokerFee),
+    // `taxRate` is deliberately left alone. A.N.A. prints the IVA amount, not
+    // the rate, and back-dividing it would mint a rate the document never
+    // stated — the policy form resolves one from the line of business instead.
+    tax: numOrUndef(item.tax, doc.extractedTax),
     total: numOrUndef(item.total, doc.extractedTotal),
     // coveragesJson / observations: freeform, keep the GMX data when present.
     coveragesJson:
@@ -680,11 +894,14 @@ function buildPolicyCreateFromDoc(
     extractedNetPremium: Prisma.Decimal | null;
     extractedPolicyFee: Prisma.Decimal | null;
     extractedBrokerFee: Prisma.Decimal | null;
+    extractedTax: Prisma.Decimal | null;
     extractedTotal: Prisma.Decimal | null;
     extractedCoveragesJson: Prisma.JsonValue | null;
     extractedPremiumPayment: string | null;
+    extractedCoveragePeriodDays: number | null;
   },
   customerId: string,
+  lookups: ResolvedLookups,
 ): Prisma.PolicyUncheckedCreateInput {
   const numOrUndef = (a: number | undefined, b: Prisma.Decimal | null): Prisma.Decimal | undefined => {
     if (a != null) return new Prisma.Decimal(a);
@@ -712,14 +929,26 @@ function buildPolicyCreateFromDoc(
   return {
     policyNumber,
     customerId,
+    policyTypeId: lookups.policyTypeId,
+    insuranceProviderId: lookups.insuranceProviderId,
     agentName: strOrUndef(item.agentName, doc.extractedAgentName),
     policyFrom: dateOrUndef(item.policyFrom, doc.extractedPolicyFrom),
     policyTo: dateOrUndef(item.policyTo, doc.extractedPolicyTo),
     policyDate: dateOrUndef(item.policyDate, doc.extractedPolicyDate),
+    // Left undefined when the document didn't print a term, so the schema
+    // default (365) stands for GMX. ANA's by-the-day policies DO print one,
+    // and the default would otherwise turn a 4-day tourist policy into an
+    // annual one on the renewals screen.
+    coveragePeriodDays:
+      item.coveragePeriodDays ?? doc.extractedCoveragePeriodDays ?? undefined,
     currency: strOrUndef(item.currency, doc.extractedCurrency) as Currency | undefined,
     netPremium: numOrUndef(item.netPremium, doc.extractedNetPremium),
     policyFee: numOrUndef(item.policyFee, doc.extractedPolicyFee),
     brokerFee: numOrUndef(item.brokerFee, doc.extractedBrokerFee),
+    // `taxRate` is deliberately left alone. A.N.A. prints the IVA amount, not
+    // the rate, and back-dividing it would mint a rate the document never
+    // stated — the policy form resolves one from the line of business instead.
+    tax: numOrUndef(item.tax, doc.extractedTax),
     total: numOrUndef(item.total, doc.extractedTotal),
     coveragesJson:
       item.coveragesJson !== undefined
@@ -765,3 +994,17 @@ function strOrUndefDb(a: string | undefined, b: string | null): string | undefin
   if (b != null && b !== "") return b;
   return undefined;
 }
+
+/** A JSON column the parser wrote as an array, read back as one. Anything
+ *  else (null, DbNull, a legacy object shape) is an empty list rather than a
+ *  crash — these columns are only ever populated by the parser, so a
+ *  surprise shape means old data, not a caller to reject. */
+function asArray<T>(value: Prisma.JsonValue | null): T[] {
+  return Array.isArray(value) ? (value as unknown as T[]) : [];
+}
+
+/** Compare identifiers the way a person would: case- and space-insensitive.
+ *  VINs and plates are printed inconsistently ("8BPX206" vs "8BPX 206"). */
+function norm(s: string): string {
+  return s.replace(/\s+/g, "").toUpperCase();
+}

apps/api/src/reports/reports.registry.ts

@@ -15,6 +15,10 @@
  */
 
 import { Prisma } from "@jorgecuadros/database";
+import {
+  BALANCE_FORWARD_TYPE,
+  periodSourceTable,
+} from "../billing/billing.service";
 import {
   intParam,
   NOT_VOIDED,
@@ -751,13 +755,22 @@ const edoCuentaDatos: ReportDef = {
   title: "Estado de cuenta",
   description:
     "Estado de cuenta de un cliente: saldos por moneda, desglose por " +
-    "ramo y concepto, y el historial completo de movimientos con saldo " +
+    "ramo y concepto, y los movimientos del año en curso con saldo " +
-    "corrido. El reporte del cliente final.",
+    "corrido, abriendo con el saldo anterior. El reporte del cliente final.",
   domain: "estado-cuenta",
   legacyName: "EDO CUENTA DATOS",
   format: "statement",
   params: [
     { key: "customerId", label: "Cliente", kind: "customer-picker" },
+    // Which period to print. Blank means the year in progress; an earlier year
+    // prints from its imported archive, the same source the on-screen
+    // statement reads.
+    {
+      key: "year",
+      label: "Periodo (año)",
+      kind: "number",
+      placeholder: "año en curso",
+    },
   ],
   columns: [
     // Statement rows carry synthetic `__kind` discriminators instead of
@@ -789,22 +802,74 @@ const edoCuentaDatos: ReportDef = {
     });
     if (!customer) return { rows: [], subtitle: "Cliente no encontrado" };
 
-    // Reuse the same NOT_VOIDED + STATEMENT_EXCLUDED_SOURCE_TABLES filter
+    // The source-table exclusion, the balance floor and the year scope below
-    // as BillingService.statement so the numbers match what the customer
+    // are BillingService.statement's, because this report and
-    // already sees in /estado-cuenta/[id].
+    // /estado-cuenta/[id] are the same statement — one printable, one on
+    // screen — and a customer holding both must not read two balances.
+    const floor = await prisma.transaction.findFirst({
+      where: {
+        customerId,
+        voidedAt: null,
+        type: { nameEn: BALANCE_FORWARD_TYPE },
+      },
+      orderBy: { transactionDate: "desc" },
+      select: { transactionDate: true },
+    });
+
+    // Which period to print. An earlier year comes from its imported archive,
+    // tagged rather than dated, exactly as the on-screen statement reads it.
+    const thisYear = new Date().getUTCFullYear();
+    const askedYear = Number(p.year);
+    const requestedYear =
+      Number.isInteger(askedYear) && askedYear > 0 ? askedYear : thisYear;
+    const isArchive = requestedYear !== thisYear;
+
     const rows = await prisma.transaction.findMany({
       where: {
         customerId,
         voidedAt: null,
-        legacySourceTable: {
+        ...(isArchive
-          notIn: [
+          ? // The archive is one period's ledger already, so the tag is the
-            "EFECTIVO",
+            // whole filter and the balance floor must not apply — the floor
-            "EFECTIVO_BACKUP",
+            // hides exactly the history this period is asking for.
-            "EFECTIVO FM3",
+            { legacySourceTable: periodSourceTable(requestedYear) }
-            "CHEQUE FM3",
+          : {
-            "IVA 2015",
+              ...(floor ? { transactionDate: { gte: floor.transactionDate } } : {}),
-          ],
+              // NULL-safe: `NULL NOT IN (...)` is NULL, not true, so a bare `notIn`
-        },
+              // drops every app-captured row (they have no legacySourceTable) — the
+              // same defect this report's on-screen twin was fixed for.
+              OR: [
+                { legacySourceTable: null },
+                {
+                  legacySourceTable: {
+                    notIn: [
+                      "EFECTIVO",
+                      "EFECTIVO_BACKUP",
+                      "EFECTIVO FM3",
+                      "CHEQUE FM3",
+                      "IVA 2015",
+                    ],
+                  },
+                },
+              ],
+              // Archive rows count as history below the year start (that is
+              // what `opening` is for, and for a customer floored by an archive
+              // it is the only carry there is) and are dropped at or above it.
+              // Same rule as the on-screen twin — see BillingService.statement.
+              AND: [
+                {
+                  OR: [
+                    { legacySourceTable: null },
+                    { legacySourceTable: { not: { startsWith: "datos2@" } } },
+                    {
+                      transactionDate: {
+                        lt: new Date(Date.UTC(requestedYear, 0, 1)),
+                      },
+                    },
+                  ],
+                },
+              ],
+            }),
       },
       orderBy: [{ transactionDate: "asc" }, { id: "asc" }],
       select: {
@@ -822,12 +887,32 @@ const edoCuentaDatos: ReportDef = {
       },
     });
 
-    // Compute running balance per currency, then return newest-first.
+    // Scoped to the calendar year and listed oldest-first, the way the legacy
+    // EDO CUENTA sheet reads. Rows from earlier years still move the running
+    // balance — they are folded into `opening` and printed as a single "saldo
+    // anterior" line, which is what a BALANCE FORWARD row is.
+    // An archive needs no fold: it *is* the period, and its own Jan-1 BALANCE
+    // FORWARD row is the carry, printed like legacy printed it.
+    const yearStart = isArchive
+      ? new Date(0)
+      : new Date(Date.UTC(requestedYear, 0, 1));
+    const year = requestedYear;
+
     const running = new Map<string, Prisma.Decimal>();
-    const movements = rows.map((r) => {
+    const opening = new Map<string, Prisma.Decimal>();
+    const visible: typeof rows = [];
+
+    const movements = rows.flatMap((r) => {
       const prev = running.get(r.currency) ?? new Prisma.Decimal(0);
       const next = prev.plus(r.amount);
       running.set(r.currency, next);
+
+      if (r.transactionDate < yearStart) {
+        opening.set(r.currency, next);
+        return [];
+      }
+
+      visible.push(r);
       return {
         date: r.transactionDate.toISOString().slice(0, 10),
         domain: r.domain,
@@ -840,14 +925,38 @@ const edoCuentaDatos: ReportDef = {
         balanceAfter: next.toFixed(2),
       };
     });
-    movements.reverse();
 
-    // Per-currency summary + per-domain breakdown.
+    // The carried balance, printed as the statement's first line — same shape
+    // as a movement row so it needs nothing special from the renderer.
+    const carried = [...opening.entries()]
+      .filter(([, amount]) => !amount.isZero())
+      .map(([currency, amount]) => ({
+        date: yearStart.toISOString().slice(0, 10),
+        domain: "UTILITY",
+        currency,
+        reference: "",
+        period: `Al cierre de ${year - 1}`,
+        checkNumber: "",
+        concept: "SALDO ANTERIOR",
+        amount: amount.toFixed(2),
+        balanceAfter: amount.toFixed(2),
+      }));
+
+    // Per-currency summary, seeded with the carried balance so it reconciles
+    // against the last running balance printed below.
     const perCurrency = new Map<
       string,
       { currency: string; charges: Prisma.Decimal; credits: Prisma.Decimal; count: number }
     >();
-    for (const r of rows) {
+    for (const [currency, amount] of opening) {
+      perCurrency.set(currency, {
+        currency,
+        charges: amount.lessThan(0) ? amount : new Prisma.Decimal(0),
+        credits: amount.lessThan(0) ? new Prisma.Decimal(0) : amount,
+        count: 0,
+      });
+    }
+    for (const r of visible) {
       const c =
         perCurrency.get(r.currency) ??
         {
@@ -881,9 +990,10 @@ const edoCuentaDatos: ReportDef = {
           count: c.count,
         })),
         { __kind: "movements-header" },
+        ...carried,
         ...movements,
       ],
-      subtitle: `${nameOf(customer)} · ${rows.length} movimientos`,
+      subtitle: `${nameOf(customer)} · ${year} · ${visible.length} movimientos`,
     };
   },
 };

apps/api/src/settings/settings.service.ts

@@ -22,6 +22,8 @@ export const SETTING_KEYS = {
   scheduleServicios: "notification.schedule.servicios",
   /** JSON cadence of the automatic pólizas renewal sweep. */
   schedulePolizas: "notification.schedule.polizas",
+  /** Whether the NUMid allocator may reuse empty portal ids. */
+  numidRecycleEmpty: "numid.recycleEmpty",
 } as const;
 
 /** Where a resolved value came from. Shown in the UI. */
@@ -169,6 +171,39 @@ export class SettingsService {
     );
   }
 
+  /**
+   * Whether the NUMid allocator may reuse empty portal ids instead of only
+   * issuing new ones.
+   *
+   * Defaults to OFF, and the default is the safety property rather than a
+   * preference: while Access remains the utilities master, every reusable id
+   * still exists in DATGRAL, and a `--sync` migration run reassigns the ref back
+   * to its Access owner (transform_customers.py:327). Recycling before utilities
+   * cuts over therefore hands out ids that quietly stop working. No env rung —
+   * this has never been an environment variable and should be flipped
+   * deliberately, in the UI, by someone who knows the cutover happened.
+   */
+  async numidRecycleEmpty(): Promise<ResolvedSetting<boolean>> {
+    const row = await this.read(SETTING_KEYS.numidRecycleEmpty);
+    if (row) {
+      return {
+        value: row.value === "true",
+        source: "db",
+        updatedAt: row.updatedAt,
+        updatedById: row.updatedById,
+      };
+    }
+    return { value: false, source: "default", updatedAt: null, updatedById: null };
+  }
+
+  async setNumidRecycleEmpty(
+    enabled: boolean,
+    userId: string,
+  ): Promise<ResolvedSetting<boolean>> {
+    await this.write(SETTING_KEYS.numidRecycleEmpty, String(enabled), userId);
+    return this.numidRecycleEmpty();
+  }
+
   private read(key: string) {
     return this.prisma.appSetting.findUnique({ where: { key } });
   }

apps/api/src/statements/ocr/tesseract.provider.spec.ts

@@ -7,8 +7,13 @@ import { parseBboxLayout } from "./tesseract.provider";
  * that grouping is what left `PERIODO FACTURADO` with no value next to it and
  * every period field empty on a batch whose text was perfectly readable.
  */
+/**
+ * Boxes are sized from the text, at 6 units a character: the reassembler now
+ * reads the space BETWEEN two boxes, so a fixed width would put a fabricated
+ * gap after every short word and every row would come back column-padded.
+ */
 function word(x: number, y: number, text: string): string {
-  return `<word xMin="${x}" yMin="${y}" xMax="${x + 20}" yMax="${y + 8}">${text}</word>`;
+  return `<word xMin="${x}" yMin="${y}" xMax="${x + text.length * 6}" yMax="${y + 8}">${text}</word>`;
 }
 
 function doc(...lines: string[]): string {
@@ -26,23 +31,57 @@ describe("parseBboxLayout", () => {
   it("rejoins a label with the value printed beside it in another flow", () => {
     const [page] = parseBboxLayout(
       doc(
-        word(20, 100, "PERIODO") + word(45, 100, "FACTURADO:"),
+        word(20, 100, "PERIODO") + word(68, 100, "FACTURADO:"),
         word(300, 100.4, "20260630-20260630"),
         padding(),
       ),
       1,
     );
     expect(page).not.toBeNull();
-    expect(page!.text).toContain("PERIODO FACTURADO: 20260630-20260630");
+    expect(page!.text).toMatch(/PERIODO FACTURADO:\s+20260630-20260630/);
   });
 
   it("keeps genuinely separate lines apart", () => {
     const [page] = parseBboxLayout(
-      doc(word(20, 100, "Cuenta:") + word(80, 100, "0900003463"), word(20, 130, "Nombre:"), padding()),
+      doc(word(20, 100, "Cuenta:") + word(68, 100, "0900003463"), word(20, 130, "Nombre:"), padding()),
       1,
     );
-    expect(page!.text.split("\n")).toContain("Cuenta: 0900003463");
+    const lines = page!.text.split("\n").map((l) => l.trim());
-    expect(page!.text.split("\n")).toContain("Nombre:");
+    expect(lines).toContain("Cuenta: 0900003463");
+    expect(lines).toContain("Nombre:");
+  });
+
+  /**
+   * The layout is data. A borderless table separates its cells with nothing
+   * but white space, so the parsers read a run of spaces as a cell boundary
+   * (`INSURED\s{2,}`) and a column offset as a column (`SUM INSURED` vs
+   * `PREMIUM`). Both regressed to nothing when this collapsed every gap to a
+   * single space, and the fixtures — taken from `pdftotext -layout`, which
+   * prints the gaps — could not see it.
+   */
+  it("preserves the gap between two cells of a borderless table", () => {
+    const [page] = parseBboxLayout(
+      doc(word(20, 100, "INSURED") + word(300, 100, "PAMELA") + word(340, 100, "WAGONER"), padding()),
+      1,
+    );
+    const line = page!.text.split("\n").find((l) => l.includes("INSURED"))!;
+    expect(line).toMatch(/INSURED\s{2,}PAMELA WAGONER/);
+  });
+
+  it("preserves the blank line between two blocks", () => {
+    const [page] = parseBboxLayout(
+      doc(word(20, 100, "Insured"), word(20, 112, "wraps"), word(20, 200, "Next"), padding()),
+      1,
+    );
+    const lines = page!.text.split("\n").map((l) => l.trim());
+    // The wrapped continuation stays attached; the next block is cut off from
+    // it, which is what stops a "join until the cell ends" walk running away.
+    expect(lines.slice(lines.indexOf("Insured"), lines.indexOf("Next") + 1)).toEqual([
+      "Insured",
+      "wraps",
+      "",
+      "Next",
+    ]);
   });
 
   it("scales point coordinates into the render's pixel space", () => {

apps/api/src/statements/ocr/tesseract.provider.ts

@@ -254,6 +254,23 @@ export function parseBboxLayout(xhtml: string, scale: number): (OcrPage | null)[
  * Rows are cut when a word's vertical centre leaves the band established by
  * the row's first word, which tolerates the sub-pixel baseline differences
  * between fonts on one line without merging two genuinely separate lines.
+ *
+ * Vertical WHITE SPACE is preserved as a blank line. Rows alone are not the
+ * whole layout: on a form, the blank between two blocks is what says where a
+ * cell's wrapped value stops, and dropping it leaves parsers that walk a
+ * block ("keep joining until the cell ends") running to the end of the page.
+ * That is not hypothetical — the GMX PVL especificación read its whole first
+ * page as the insured's name, because the fixtures were taken from
+ * `pdftotext -layout` (which prints the blanks) while the runtime fed it this
+ * function's output (which did not).
+ *
+ * Horizontal white space is preserved the same way, by padding each word out
+ * to its own column. The same fixture mismatch bit here: a run of spaces is
+ * the ONLY thing separating two cells of a borderless table, so ANA's
+ * `INSURED\s{2,}` label matches and its `SUM INSURED` / `PREMIUM` column
+ * split (taken from `head.search()` offsets) both need real offsets. Joining
+ * on one space put every driver's-policy premium in the sum-insured column
+ * and left the phone glued to the insured's name.
  */
 function toVisualRows(words: OcrWord[]): string {
   const centre = (w: OcrWord) => w.top + w.height / 2;
@@ -281,14 +298,85 @@ function toVisualRows(words: OcrWord[]): string {
   }
   if (current.length) rows.push(current);
 
-  return rows
+  const charWidth = estimateCharWidth(words);
-    .map((r) =>
+  const out: string[] = [];
-      [...r]
+  rows.forEach((r, i) => {
-        .sort((a, b) => a.left - b.left)
+    if (i > 0 && isBlankBetween(rows[i - 1], r)) out.push("");
-        .map((w) => w.text)
+    out.push(layoutRow(r, charWidth));
-        .join(" "),
+  });
-    )
+  return out.join("\n");
-    .join("\n");
+}
+
+/**
+ * One row rendered at its printed column offsets.
+ *
+ * Words that merely follow one another inside the same cell are separated by
+ * exactly one space, whatever the column arithmetic says: one `charWidth` for
+ * a page that mixes fonts leaves a rounding error on every word, and letting
+ * that accumulate sprinkles `\s{2,}` runs through ordinary prose — which is
+ * the very thing the parsers read as a cell boundary. Only a gap wide enough
+ * to be deliberate (more than one blank character) is rendered as one, and
+ * only there is the word re-anchored to its true column, so the offsets a
+ * column split depends on stay honest while values stay clean.
+ */
+function layoutRow(row: OcrWord[], charWidth: number): string {
+  let line = "";
+  let right = 0;
+
+  for (const w of [...row].sort((a, b) => a.left - b.left)) {
+    const col = Math.round(w.left / charWidth);
+    if (!line.length) {
+      line = " ".repeat(Math.max(0, col));
+    } else if (w.left - right > charWidth * 1.5) {
+      line += " ".repeat(Math.max(2, col - line.length));
+    } else {
+      line += " ";
+    }
+    line += w.text;
+    right = w.left + w.width;
+  }
+
+  return line.trimEnd();
+}
+
+/**
+ * Width of one character, in the same units the word boxes use.
+ *
+ * The median of each word's own width-per-character: robust to the handful of
+ * oversized headings and to the wide-tracked letterhead, both of which would
+ * drag a mean. Only words of 3+ characters vote, since a one-character box is
+ * mostly side bearing. Falls back to a value derived from line height when a
+ * page has nothing long enough to measure.
+ */
+function estimateCharWidth(words: OcrWord[]): number {
+  const samples = words
+    .filter((w) => w.text.length >= 3 && w.width > 0)
+    .map((w) => w.width / w.text.length)
+    .sort((a, b) => a - b);
+  if (samples.length) return samples[Math.floor(samples.length / 2)];
+  const heights = words.map((w) => w.height).filter((h) => h > 0);
+  return heights.length ? Math.max(...heights) / 2 : 1;
+}
+
+/**
+ * Does the space between two consecutive rows read as an empty line?
+ *
+ * Measured against the taller of the two rows so a heading and its body text
+ * are judged on their own scale. On the real documents the two populations do
+ * not overlap: consecutive lines of one paragraph sit at 0.3–1.1 line heights
+ * apart, and anything the reader sees as blank-separated starts at 2.1. The
+ * threshold is placed in that empty middle, biased high — a missed blank only
+ * restores today's behaviour, while a spurious one would cut a wrapped value
+ * short.
+ */
+function isBlankBetween(prev: OcrWord[], row: OcrWord[]): boolean {
+  const bottom = Math.max(...prev.map((w) => w.top + w.height));
+  const top = Math.min(...row.map((w) => w.top));
+  const unit = Math.max(
+    ...prev.map((w) => w.height),
+    ...row.map((w) => w.height),
+  );
+  return unit > 0 && top - bottom > unit * 1.6;
 }
 
 /**

apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jorgecuadros/web",
-  "version": "1.0.7",
+  "version": "1.0.25",
   "private": true,
   "scripts": {
     "dev": "next dev -p 4500",

apps/web/src/app/catalogos/page.tsx

@@ -18,6 +18,10 @@ const TYPE: ChildConfig = {
   fields: [
     { key: "name", label: "Nombre" },
     { key: "shortDescription", label: "Descripción" },
+    // The rate is stored as a fraction, not a percentage, and the label has to
+    // say so: 8 typed here would tax a $600 premium $4,800. The API rejects
+    // anything above 1 rather than trusting the label alone.
+    { key: "taxRate", label: "IVA (0.08 = 8%)", type: "number", step: "0.0001" },
   ],
 };
 const ADJUSTER: ChildConfig = {

apps/web/src/app/clientes/[id]/page.tsx

@@ -7,6 +7,7 @@ import { ContextReports } from "@/components/ContextReports";
 import {
   archiveCustomer,
   getCustomer,
+  grantPortalAccess,
   policyDocumentDownloadUrl,
   propertyDocumentDownloadUrl,
   restoreCustomer,
@@ -127,6 +128,7 @@ function Detail({ id }: { id: string }) {
         customerId={data.id}
         summary={data.transactionSummary}
         transactions={data.transactions}
+        year={data.transactionYear}
       />
       <DocumentosSection data={data} />
     </div>
@@ -151,9 +153,43 @@ function CustomerActions({
 }) {
   const canEdit = useCan("customer:update");
   const canDelete = useCan("customer:delete");
+  const canGrantPortal = useCan("customer:portal-access");
   const [busy, setBusy] = useState(false);
   const archived = customer.archivedAt != null;
 
+  // The portal NUMid is a legacy ref, not a column: (utilities, DATGRAL) is the
+  // "Security Number" my.jorgecuadros.com asks for. An insurance ref is a
+  // different id space entirely and does not let anyone log in, so both columns
+  // are checked — matching on sourceTable alone would hide the button from
+  // customers who cannot actually reach the portal.
+  const hasPortalId = customer.legacyRefs.some(
+    (r) => r.sourceSystem === "utilities" && r.sourceTable === "DATGRAL",
+  );
+
+  async function grantPortal() {
+    if (
+      !window.confirm(
+        "¿Asignar un número de portal a este cliente? Con él podrá entrar a " +
+          "my.jorgecuadros.com.",
+      )
+    )
+      return;
+    setBusy(true);
+    try {
+      const { numid, origin } = await grantPortalAccess(customer.id);
+      window.alert(
+        origin === "existing"
+          ? `Este cliente ya tenía el número de portal ${numid}.`
+          : `Número de portal asignado: ${numid}.`,
+      );
+      onChange();
+    } catch (e) {
+      window.alert((e as Error)?.message ?? "No se pudo completar la acción.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
   async function toggleArchive() {
     const verb = archived ? "restaurar" : "archivar";
     if (!window.confirm(`¿Seguro que desea ${verb} este cliente?`)) return;
@@ -169,11 +205,23 @@ function CustomerActions({
     }
   }
 
-  if (!canEdit && !canDelete) return null;
+  const showPortal = canGrantPortal && !hasPortalId && !archived;
+  if (!canEdit && !canDelete && !showPortal) return null;
 
   return (
     <div className="row-actions">
       {archived && <span className="badge badge-negative">Archivado</span>}
+      {showPortal && (
+        <button
+          type="button"
+          className="btn btn-outline"
+          onClick={grantPortal}
+          disabled={busy}
+          title="Asigna el número que el cliente usa para entrar al portal"
+        >
+          Habilitar acceso al portal
+        </button>
+      )}
       {canEdit && (
         <Link href={`/clientes/${customer.id}/editar`} className="btn btn-outline">
           Editar
@@ -699,16 +747,18 @@ function EstadoCuentaSection({
   customerId,
   summary,
   transactions,
+  year,
 }: {
   customerId: string;
   summary: TransactionSummaryRow[];
   transactions: Transaction[];
+  year: number;
 }) {
   return (
     <section className="section">
       <SectionHead
         rule="cuenta"
-        title="Estado de cuenta"
+        title={`Estado de cuenta ${year}`}
         count={transactions.length}
         countSuffix="movimientos"
       />
@@ -735,7 +785,7 @@ function EstadoCuentaSection({
 
       <div className="card">
         {transactions.length === 0 ? (
-          <div className="empty-inline">Sin movimientos registrados.</div>
+          <div className="empty-inline">Sin movimientos en {year}.</div>
         ) : (
           <div className="tx-scroll">
             <table className="tx-table">
@@ -757,11 +807,11 @@ function EstadoCuentaSection({
             </table>
           </div>
         )}
-        {transactions.length >= 100 && (
+        <div className="section-note" style={{ padding: "0 16px 14px" }}>
-          <div className="section-note" style={{ padding: "0 16px 14px" }}>
+          Movimientos de {year}, del más antiguo al más reciente. Los saldos de
-            Mostrando los 100 movimientos más recientes.
+          arriba son el saldo actual por línea de negocio — los mismos del
-          </div>
+          estado de cuenta, no la suma del año.
-        )}
+        </div>
       </div>
       {transactions.length > 0 && (
         <p className="section-note">

apps/web/src/app/estado-cuenta/[id]/page.tsx

@@ -36,10 +36,14 @@ import type {
  * charge and an insurance payment finally sit on the same page, under the same
  * person, with a running balance.
  *
- * The running balance is per currency (the API accumulates it chronologically
+ * The running balance is per currency, so the movement table is scoped to one
- * before handing the list back newest-first), so the movement table is scoped
+ * currency at a time — a column that alternated between pesos and dollars would
- * to one currency at a time — a column that alternated between pesos and
+ * be a meaningless number.
- * dollars would be a meaningless number.
+ *
+ * Like the legacy EDO CUENTA report, the table covers one calendar year and runs
+ * oldest-first, opening on the balance carried in from before it. The period
+ * selector switches years; earlier ones are served from the imported archive of
+ * that year, which is how legacy kept them — one table per closed year.
  */
 export default function EstadoCuentaDetailPage({
   params,
@@ -65,19 +69,27 @@ function StatementView({ id }: { id: string }) {
 
   const [currency, setCurrency] = useState<LedgerCurrency | null>(null);
   const [domain, setDomain] = useState<TransactionDomain | "">("");
+  /** null = the current period; the API decides what that is. */
+  const [year, setYear] = useState<number | null>(null);
 
   function reload() {
     let alive = true;
     setLoading(true);
     setError(null);
-    getStatement(id)
+    getStatement(id, year ?? undefined)
       .then((d) => {
         if (!alive) return;
         setData(d);
         // Default to the currency the customer actually moves the most in;
-        // preserve a previously-chosen currency across reloads.
+        // preserve a previously-chosen currency across reloads — but only if
+        // the loaded period still has it. Switching to a year the customer
+        // never moved dollars in would otherwise leave the picker on USD with
+        // no matching option, showing an empty table for a year that has rows.
         const busiest = [...d.summary].sort((a, b) => b.count - a.count)[0];
-        setCurrency((prev) => prev ?? busiest?.currency ?? "MXN");
+        const fallback = busiest?.currency ?? "MXN";
+        setCurrency((prev) =>
+          prev && d.summary.some((s) => s.currency === prev) ? prev : fallback,
+        );
         setLoading(false);
       })
       .catch((e) => {
@@ -99,7 +111,7 @@ function StatementView({ id }: { id: string }) {
     getBillingFacets().then(setFacets).catch(() => setFacets(null));
     return cleanup;
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [id]);
+  }, [id, year]);
 
   const movements = useMemo(() => {
     if (!data || !currency) return [];
@@ -194,7 +206,7 @@ function StatementView({ id }: { id: string }) {
       <section className="section">
         <SectionHead
           rule="cuenta"
-          title="Movimientos"
+          title={`Movimientos ${data.year}`}
           count={movements.length}
           countSuffix={movements.length === 1 ? "movimiento" : "movimientos"}
           right={
@@ -227,6 +239,26 @@ function StatementView({ id }: { id: string }) {
         )}
 
         <div className="filter-row">
+          {/* Only the periods this customer has. A year with no archive would
+              render an empty table that reads as "no hubo movimientos" when the
+              truth is that the year was never imported. */}
+          {data.availableYears.length > 1 && (
+            <label className="filter-field">
+              <span className="filter-label">Periodo</span>
+              <select
+                className="input select"
+                value={data.year}
+                onChange={(e) => setYear(Number(e.target.value))}
+              >
+                {data.availableYears.map((y) => (
+                  <option key={y} value={y}>
+                    {y}
+                    {y === data.availableYears[0] ? " (en curso)" : ""}
+                  </option>
+                ))}
+              </select>
+            </label>
+          )}
           <label className="filter-field">
             <span className="filter-label">Moneda</span>
             <select
@@ -260,7 +292,7 @@ function StatementView({ id }: { id: string }) {
         <div className="card">
           {movements.length === 0 ? (
             <div className="empty-inline">
-              Sin movimientos en {currency}
+              Sin movimientos de {data.year} en {currency}
               {domain ? ` para ${domainLabel(domain)}` : ""}.
             </div>
           ) : (
@@ -282,6 +314,26 @@ function StatementView({ id }: { id: string }) {
                   </tr>
                 </thead>
                 <tbody>
+                  {/*
+                    The carried balance, shown the way the legacy report shows
+                    it: a BALANCE FORWARD line above the year's movements. It
+                    only appears when there is something to carry — when the
+                    customer's opening-balance row is itself dated inside this
+                    year (the usual case) it is listed as an ordinary movement
+                    and this row is zero, so it is left out.
+
+                    Suppressed under a business-line filter: the carried balance
+                    is the customer's, across both lines, and printing it above
+                    one line's rows would read as that line's opening balance.
+                  */}
+                  {!domain && Number(active?.opening ?? 0) !== 0 && (
+                    <OpeningRow
+                      opening={active!.opening}
+                      currency={currency}
+                      year={data.year}
+                      canVoid={canVoid}
+                    />
+                  )}
                   {movements.map((m) => (
                     <StatementRow
                       key={m.id}
@@ -481,6 +533,44 @@ function ConceptosSection({
   );
 }
 
+/** The balance carried into the statement year — legacy's BALANCE FORWARD. */
+function OpeningRow({
+  opening,
+  currency,
+  year,
+  canVoid,
+}: {
+  opening: string;
+  currency: LedgerCurrency;
+  year: number;
+  canVoid: boolean;
+}) {
+  return (
+    <tr>
+      <td className="mono" style={{ whiteSpace: "nowrap" }}>
+        {formatDate(`${year}-01-01T00:00:00.000Z`)}
+      </td>
+      <td className="tx-domain-cell">Ambas líneas</td>
+      <td>
+        Saldo anterior
+        <div className="tx-concept">Al cierre de {year - 1}</div>
+      </td>
+      <td className="tx-ref">—</td>
+      <td className="num">
+        <span className={`tx-amount ${Number(opening) < 0 ? "neg" : "pos"}`}>
+          {formatMoney(opening, currency)}
+        </span>
+      </td>
+      <td className="num">
+        <span className={`bal-running ${balanceTone(opening)}`}>
+          {formatMoney(opening, currency)}
+        </span>
+      </td>
+      {canVoid && <td />}
+    </tr>
+  );
+}
+
 function StatementRow({
   m,
   canVoid,

apps/web/src/app/globals.css

@@ -926,6 +926,15 @@ button {
   color: var(--ink-soft);
   margin-bottom: 0.4375rem;
 }
+/* Sub-label under an input: the computed figure behind an override field, or
+   why a field is disabled. Quiet enough not to compete with .field-label. */
+.field-hint {
+  display: block;
+  font-size: 0.75rem;
+  line-height: 1.35;
+  color: var(--muted-2);
+  margin-top: 0.3125rem;
+}
 .input {
   width: 100%;
   font-family: inherit;
@@ -940,6 +949,12 @@ button {
 .input::placeholder {
   color: var(--muted-2);
 }
+.input:disabled,
+.select:disabled {
+  background: var(--surface-2, var(--surface));
+  color: var(--muted-2);
+  cursor: not-allowed;
+}
 .input:focus {
   outline: none;
   border-color: var(--brand-600);
@@ -3114,3 +3129,61 @@ button {
   border-color: var(--brand-500);
   color: var(--brand-700);
 }
+
+/* ============================================================================
+   Layout + text utilities the screens already assumed
+   Several components were written against these names before any rule
+   defined them, so they rendered as bare inline spans. The visible symptom
+   was the policy OCR review header running together —
+   "Para revisarPágina 1700489616· PAMELA DENISE WAGONERLICENCIASANA" —
+   because JSX drops the newline between sibling elements and the `gap` those
+   call sites pass does nothing without a flex container.
+   ========================================================================== */
+.row {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+/* The muted line under a page title, and the same voice reused inline. Only
+   the block form takes a margin — as a flex child it would shift the item
+   off the row's centre line. */
+.page-sub {
+  color: var(--muted);
+  font-size: 0.875rem;
+}
+p.page-sub {
+  margin: 0.25rem 0 0;
+}
+/* A neutral chip. Same shape as `.badge` so the OCR statuses, policy type and
+   carrier read as the labels they are rather than as running prose. */
+.tag {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  padding: 0.1875rem 0.5625rem;
+  border-radius: 999px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  line-height: 1.4;
+  white-space: nowrap;
+  background: var(--paper-2);
+  color: var(--muted);
+  border: 1px solid var(--line-strong);
+}
+/* The warning sibling of `.state-error`, used where a page needs a human to
+   choose between candidates rather than reporting a failure. */
+.state-warn {
+  background: var(--servicios-tint);
+  border: 1px solid rgba(154, 106, 18, 0.25);
+  color: var(--servicios-ink);
+  border-radius: var(--radius);
+  padding: 1rem 1.125rem;
+  font-size: 0.875rem;
+}

apps/web/src/app/layout.tsx

@@ -8,19 +8,18 @@ export const metadata = {
     "Plataforma interna unificada de clientes, servicios y seguros.",
 };
 
-// The browser talks to the API cross-origin, so it needs the API URL at
+// API_ORIGIN is an OPTIONAL override, read here on the server per request and
-// runtime. NEXT_PUBLIC_* would bake it at build time (one URL per image); we
+// injected as window.__API_ORIGIN__ (see lib/api.ts). NEXT_PUBLIC_* would bake
-// want the URL to come from the deploy .env instead. So read it here on the
+// it at build time (one URL per image); reading it here keeps one image usable
-// server per request and inject it as window.__API_ORIGIN__ (see lib/api.ts).
+// anywhere. Left unset — the normal case — this injects the empty string and
-// force-dynamic guarantees process.env is read at request time, never baked
+// lib/api.ts derives the origin from window.location instead, so the app
-// into a static prerender.
+// follows the server when it moves without an env edit. force-dynamic
+// guarantees process.env is read at request time, never baked into a static
+// prerender.
 export const dynamic = "force-dynamic";
 
 export default function RootLayout({ children }: { children: ReactNode }) {
-  const apiOrigin =
+  const apiOrigin = process.env.API_ORIGIN ?? "";
-    process.env.API_ORIGIN ??
-    process.env.NEXT_PUBLIC_API_ORIGIN ??
-    "http://localhost:3001";
   // Same reason as the API origin: read on the server per request so the built
   // image is not pinned to one build identity in its client bundle.
   const build = readBuildInfoFromEnv();

apps/web/src/app/operaciones/page.tsx

@@ -14,18 +14,24 @@ import {
   deleteBackup,
   deleteIngest,
   getOpsJob,
+  getReplicationStatus,
   listBackups,
   listIngest,
   listOpsJobs,
   startOpsJob,
   uploadIngest,
+  verifyReplication,
 } from "@/lib/api";
 import type { UploadProgress } from "@/lib/api";
 import type {
+  ApplyProgress,
   BackupFile,
   IngestFile,
   OpsJob,
   OpsJobKind,
+  GtidDrift,
+  ReplicationStatus,
+  VerifyResult,
 } from "@/lib/types";
 
 const INGEST_MAX_BYTES = 2 * 1024 * 1024 * 1024;
@@ -56,11 +62,13 @@ function Operaciones() {
   const [notice, setNotice] = useState<string | null>(null);
   const [confirm, setConfirm] = useState<ConfirmState>(null);
   const [confirmText, setConfirmText] = useState("");
+  const [forceFull, setForceFull] = useState(false);
   const [uploading, setUploading] = useState<string | null>(null);
   const [progress, setProgress] = useState<UploadProgress | null>(null);
   const [starting, setStarting] = useState(false);
 
   const fileInputs = useRef<Record<string, HTMLInputElement | null>>({});
+  const periodInput = useRef<HTMLInputElement | null>(null);
 
   const refreshLists = useCallback(() => {
     listIngest().then(setIngest).catch(() => setIngest([]));
@@ -136,6 +144,20 @@ function Operaciones() {
     }
   }
 
+  /** Upload a prior-period archive under its own filename. */
+  async function handleUploadPeriod(file: File | undefined) {
+    if (!file) return;
+    if (!/^\d{4}\.accdb$/i.test(file.name)) {
+      setError(
+        `"${file.name}" no es un archivo de periodo. Debe llamarse AAAA.accdb, por ejemplo 2025.accdb.`,
+      );
+      if (periodInput.current) periodInput.current.value = "";
+      return;
+    }
+    await handleUpload(file.name, file);
+    if (periodInput.current) periodInput.current.value = "";
+  }
+
   async function handleDeleteIngest(name: string) {
     setError(null);
     try {
@@ -156,12 +178,12 @@ function Operaciones() {
     }
   }
 
-  async function start(kind: OpsJobKind, file?: string) {
+  async function start(kind: OpsJobKind, file?: string, force?: boolean) {
     setError(null);
     setNotice(null);
     setStarting(true);
     try {
-      const job = await startOpsJob(kind, file);
+      const job = await startOpsJob(kind, file, force);
       setActiveJob(job);
       setJobs((prev) => (prev ? [job, ...prev] : [job]));
     } catch (e) {
@@ -174,6 +196,9 @@ function Operaciones() {
   function askConfirm(state: ConfirmState) {
     setConfirm(state);
     setConfirmText("");
+    // Always re-armed: ticking "delete native rows" once must not carry into
+    // the next reimport.
+    setForceFull(false);
     setError(null);
     setNotice(null);
   }
@@ -182,12 +207,16 @@ function Operaciones() {
     if (!confirm) return;
     const c = confirm;
     setConfirm(null);
-    if (c.kind === "REIMPORT") await start("REIMPORT");
+    if (c.kind === "REIMPORT") await start("REIMPORT", undefined, forceFull);
     else if (c.kind === "SYNC") await start("SYNC");
     else await start("RESTORE", c.file);
   }
 
-  const ingestReady = (ingest ?? []).every((f) => f.present);
+  // Only the four fixed Access sources gate a run. Period archives are
+  // optional extras — having none simply means no prior years are available.
+  const ingestReady = (ingest ?? [])
+    .filter((f) => f.periodYear === null)
+    .every((f) => f.present);
 
   return (
     <>
@@ -223,16 +252,20 @@ function Operaciones() {
               </button>
             )}
           </div>
+          <JobProgressBar job={activeJob} />
           <pre className="ops-log">{activeJob.log || "Iniciando…"}</pre>
         </div>
       )}
 
+      <ReplicationCard />
+
       {/* Ingest folder */}
       <div className="card" style={{ padding: 20, marginBottom: 20 }}>
         <h2 className="section-title">Carpeta de ingesta</h2>
         <p className="inline-form-note">
-          Los cuatro archivos originales de Access. La reimportación y la
+          Los cuatro archivos originales de Access, más los archivos de periodos
-          sincronización leen de aquí. Tamaño máximo por archivo: {formatBytes(INGEST_MAX_BYTES)}.
+          anteriores. La reimportación y la sincronización leen de aquí. Tamaño
+          máximo por archivo: {formatBytes(INGEST_MAX_BYTES)}.
         </p>
         <div className="tx-scroll">
           <table className="tx-table">
@@ -249,7 +282,14 @@ function Operaciones() {
               {(ingest ?? []).map((f) => (
                 <Fragment key={f.name}>
                   <tr>
-                    <td className="mono">{f.name}</td>
+                    <td className="mono">
+                      {f.name}
+                      {f.periodYear !== null && (
+                        <span className="badge" style={{ marginLeft: 8 }}>
+                          periodo {f.periodYear}
+                        </span>
+                      )}
+                    </td>
                     <td>
                       <span className={`badge ${f.present ? "badge-positive" : "badge-negative"}`}>
                         {f.present ? "Presente" : "Falta"}
@@ -300,6 +340,33 @@ function Operaciones() {
             </tbody>
           </table>
         </div>
+
+        {/* A period archive that has never been uploaded has no row to click,
+            so it needs its own entry point. The file names itself: the archive
+            IS `2025.accdb`, and that name is what declares the period, so the
+            control reads it off the chosen file rather than asking twice. */}
+        <div className="row-actions" style={{ marginTop: 16 }}>
+          <input
+            ref={periodInput}
+            type="file"
+            accept=".accdb"
+            style={{ display: "none" }}
+            onChange={(e) => handleUploadPeriod(e.target.files?.[0])}
+          />
+          <button
+            className="btn btn-outline"
+            type="button"
+            disabled={uploading !== null}
+            onClick={() => periodInput.current?.click()}
+          >
+            Agregar periodo anterior…
+          </button>
+          <span className="inline-form-note">
+            Un archivo de Access por año cerrado, nombrado con su periodo:{" "}
+            <span className="mono">2025.accdb</span>. Aporta el año anterior al
+            estado de cuenta; no altera el saldo actual.
+          </span>
+        </div>
       </div>
 
       {/* Operations */}
@@ -472,11 +539,24 @@ function Operaciones() {
             </h2>
             <p className="inline-form-note">
               {confirm.kind === "REIMPORT"
-                ? "Esto BORRA todos los datos actuales (incluidos los capturados a mano) y reconstruye desde los archivos de ingesta. Se creará un respaldo previo automático."
+                ? "Esto BORRA todos los datos actuales y reconstruye desde los archivos de ingesta. Se creará un respaldo previo automático. Si la base contiene registros que sólo existen en la plataforma (clientes creados aquí, números de portal asignados, pólizas capturadas por OCR, movimientos capturados), la operación se detiene y los enumera sin tocar nada."
                 : confirm.kind === "SYNC"
                   ? "Se creará un respaldo previo automático. Luego se importarán al sistema los registros nuevos del legado y se eliminarán los del legado que ya no aparezcan en los archivos de ingesta. Los datos capturados a mano NO se borran."
                   : `Esto sobreescribe la base de datos completa con “${confirm.file}”. Se recomienda crear un respaldo antes.`}
             </p>
+            {confirm.kind === "REIMPORT" && (
+              <label className="inline-form-note" style={{ display: "block" }}>
+                <input
+                  type="checkbox"
+                  checked={forceFull}
+                  onChange={(e) => setForceFull(e.target.checked)}
+                  style={{ marginRight: 8 }}
+                />
+                Borrar también los registros que sólo existen en la plataforma
+                (ignorar la verificación). Sólo marque esto si de verdad quiere
+                perderlos.
+              </label>
+            )}
             <label className="field">
               <span className="field-label">Escriba CONFIRMAR para continuar</span>
               <input
@@ -596,3 +676,363 @@ function OpTile({
     </div>
   );
 }
+
+/**
+ * Health of the read replica behind my.jorgecuadros.com.
+ *
+ * Worth a panel because the failure mode is silent: a replica whose SQL thread
+ * has stopped keeps answering queries, just with data frozen at the moment it
+ * stopped. Nothing on the customer site looks wrong — the balances are simply
+ * out of date — so without this the only signal is a customer complaining.
+ */
+function ReplicationCard() {
+  const [status, setStatus] = useState<ReplicationStatus | null>(null);
+  const [failed, setFailed] = useState(false);
+  const [verify, setVerify] = useState<VerifyResult | null>(null);
+  const [verifying, setVerifying] = useState(false);
+  const [verifyError, setVerifyError] = useState<string | null>(null);
+
+  const load = useCallback(() => {
+    getReplicationStatus()
+      .then((s) => {
+        setStatus(s);
+        setFailed(false);
+      })
+      .catch(() => setFailed(true));
+  }, []);
+
+  const runVerify = useCallback(() => {
+    setVerifying(true);
+    setVerifyError(null);
+    verifyReplication()
+      .then(setVerify)
+      .catch((e: unknown) =>
+        setVerifyError(e instanceof Error ? e.message : "No se pudo comparar."),
+      )
+      .finally(() => setVerifying(false));
+  }, []);
+
+  useEffect(() => {
+    load();
+    const t = setInterval(load, 30_000);
+    return () => clearInterval(t);
+  }, [load]);
+
+  // Not configured is the normal state in dev and before cutover, so it is a
+  // quiet note rather than an alarm — showing red here would train people to
+  // ignore the card.
+  if (failed || (status && !status.configured)) {
+    return (
+      <div className="card" style={{ padding: 20, marginBottom: 20 }}>
+        <h2 className="section-title">Réplica del sitio de clientes</h2>
+        <p className="inline-form-note">
+          {failed
+            ? "No se pudo consultar el estado de la réplica."
+            : "No configurada en este entorno."}
+        </p>
+      </div>
+    );
+  }
+
+  if (!status) {
+    return (
+      <div className="card" style={{ padding: 20, marginBottom: 20 }}>
+        <h2 className="section-title">Réplica del sitio de clientes</h2>
+        <p className="inline-form-note">Consultando…</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="card" style={{ padding: 20, marginBottom: 20 }}>
+      <div className="row-actions" style={{ justifyContent: "space-between" }}>
+        <h2 className="section-title" style={{ margin: 0 }}>
+          Réplica del sitio de clientes{" "}
+          <span className={`badge ${status.healthy ? "badge-positive" : "badge-negative"}`}>
+            {status.healthy ? "Replicando" : "Detenida"}
+          </span>
+        </h2>
+        <button className="btn btn-ghost" type="button" onClick={load}>
+          Actualizar
+        </button>
+      </div>
+
+      {status.problem && (
+        <div className="state-box state-error" style={{ marginTop: 12 }}>
+          {status.problem}
+        </div>
+      )}
+
+      <div className="kv-grid" style={{ paddingLeft: 0, paddingRight: 0 }}>
+        <KV label="Servidor" value={status.host} />
+        <KV label="Origen" value={status.sourceHost} />
+        <KV label="Hilo de E/S" value={status.ioRunning} />
+        <KV label="Hilo SQL" value={status.sqlRunning} />
+        {/* Never render a null lag as "0 s": MySQL reports NULL whenever a
+            thread is down, so the honest word is "unknown", not "up to date". */}
+        <KV
+          label="Retraso"
+          value={status.secondsBehind === null ? "sin dato" : `${status.secondsBehind} s`}
+        />
+        <KV label="Pendiente de aplicar" value={backlogLabel(status.apply)} />
+        <KV label="Diferencia con el maestro" value={driftLabel(status.drift)} />
+        <KV label="Consultado" value={formatDateTime(status.checkedAt)} />
+      </div>
+
+      <ApplyProgressBar apply={status.apply} />
+
+      {/* Only worth showing when it is not zero, and even then as a note rather
+          than a warning: these are the seed load's own transactions, and they
+          are inert until someone tries to promote this box. */}
+      {status.drift !== null && status.drift.localTransactions > 0 && (
+        <p className="inline-form-note" style={{ marginTop: 12 }}>
+          La réplica tiene {status.drift.localTransactions.toLocaleString("es-MX")} transacciones
+          propias (de la carga inicial). No se propagan y no afectan la lectura; sólo importarían
+          si este servidor pasara a ser maestro.
+        </p>
+      )}
+
+      <VerifyPanel
+        result={verify}
+        running={verifying}
+        error={verifyError}
+        onRun={runVerify}
+      />
+    </div>
+  );
+}
+
+/**
+ * Row-by-row comparison against the master, on demand.
+ *
+ * Separate from the polled fields because it costs a full scan of both servers.
+ * It is the only check here that can catch a row changed on the replica by
+ * something other than replication — the GTID and lag figures would both still
+ * read perfectly healthy in that case.
+ */
+function VerifyPanel({
+  result,
+  running,
+  error,
+  onRun,
+}: {
+  result: VerifyResult | null;
+  running: boolean;
+  error: string | null;
+  onRun: () => void;
+}) {
+  return (
+    <div style={{ marginTop: 16, borderTop: "1px solid var(--border)", paddingTop: 12 }}>
+      <div className="row-actions" style={{ justifyContent: "space-between" }}>
+        <span className="inline-form-note" style={{ margin: 0 }}>
+          Compara fila por fila las 8 tablas que lee el sitio de clientes. Recorre ambos
+          servidores por completo, así que tarda.
+        </span>
+        <button className="btn btn-ghost" type="button" onClick={onRun} disabled={running}>
+          {running ? "Comparando…" : "Comparar con el maestro"}
+        </button>
+      </div>
+
+      {error && (
+        <div className="state-box state-error" style={{ marginTop: 12 }}>
+          {error}
+        </div>
+      )}
+
+      {result?.problem && (
+        <div className="state-box state-error" style={{ marginTop: 12 }}>
+          {result.problem}
+        </div>
+      )}
+
+      {result && !result.problem && (
+        <>
+          <p style={{ marginTop: 12, marginBottom: 8 }}>
+            <span className={`badge ${result.identical ? "badge-positive" : "badge-negative"}`}>
+              {result.identical ? "Idénticas" : "Hay diferencias"}
+            </span>{" "}
+            <span className="inline-form-note">
+              {formatDateTime(result.checkedAt)} · {(result.elapsedMs / 1000).toFixed(1)} s
+            </span>
+          </p>
+          <div style={{ overflowX: "auto" }}>
+            <table className="data-table">
+              <thead>
+                <tr>
+                  <th>Tabla</th>
+                  <th style={{ textAlign: "right" }}>Maestro</th>
+                  <th style={{ textAlign: "right" }}>Réplica</th>
+                  <th>Estado</th>
+                </tr>
+              </thead>
+              <tbody>
+                {result.tables.map((t) => (
+                  <tr key={t.table}>
+                    <td>{t.table}</td>
+                    {/* -1 is the sentinel for "that server did not answer for
+                        this table", which is not the same as zero rows. */}
+                    <td style={{ textAlign: "right" }}>
+                      {t.masterRows < 0 ? "—" : t.masterRows.toLocaleString("es-MX")}
+                    </td>
+                    <td style={{ textAlign: "right" }}>
+                      {t.replicaRows < 0 ? "—" : t.replicaRows.toLocaleString("es-MX")}
+                    </td>
+                    <td>
+                      <span className={`badge ${t.matches ? "badge-positive" : "badge-negative"}`}>
+                        {t.matches
+                          ? "igual"
+                          : t.masterRows !== t.replicaRows
+                            ? "difieren en filas"
+                            : "difieren en contenido"}
+                      </span>
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Transactions the master has executed that the replica has not.
+ *
+ * Rendered as its own line rather than folded into the lag figure because the
+ * two disagree in exactly the case that matters: a disconnected I/O thread
+ * reports 0 seconds of lag (no event has arrived to be late) while this number
+ * climbs.
+ */
+function driftLabel(drift: GtidDrift | null): string {
+  // Null means the master could not be reached. Saying "al día" here would be a
+  // lie of the worst kind — it is the reading a broken check produces.
+  if (drift === null) return "sin dato";
+  if (drift.missingTransactions === 0) return "al día";
+  return `${drift.missingTransactions.toLocaleString("es-MX")} transacciones atrás`;
+}
+
+/**
+ * Bytes the replica has fetched but not yet applied.
+ *
+ * Kept separate from the lag figure because it answers a question the lag
+ * cannot: while the SQL thread chews through one big transaction, the seconds
+ * counter can hold still, but this number visibly falls.
+ */
+function backlogLabel(apply: ApplyProgress | null): string {
+  if (!apply) return "sin dato";
+  // Different source binlog files means the replica is whole files behind and
+  // the byte delta is not a delta at all — positions restart in each new file.
+  if (!apply.sameFile) return "más de un archivo de binlog";
+  if (apply.backlogBytes === 0) return "al día";
+  return formatBytes(apply.backlogBytes);
+}
+
+/**
+ * Applied-vs-fetched bar. Rendered only when both threads are on the same
+ * source binlog file, because that is the only case where the percentage is
+ * arithmetic rather than a guess.
+ */
+function ApplyProgressBar({ apply }: { apply: ApplyProgress | null }) {
+  if (!apply || !apply.sameFile || apply.percent === null) return null;
+
+  return (
+    <div className="upload-progress" style={{ marginTop: 12 }}>
+      <div
+        className="progress-track"
+        role="progressbar"
+        aria-valuenow={apply.percent}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-label="Eventos aplicados de los recibidos"
+      >
+        <div className="progress-fill" style={{ width: `${apply.percent}%` }} />
+      </div>
+      <div className="upload-progress-stats mono">
+        <span>{apply.percent}% aplicado</span>
+        <span>
+          {apply.sourceLogFile} · {apply.execPos.toLocaleString("es-MX")} /{" "}
+          {apply.readPos.toLocaleString("es-MX")}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+/** Matches the KV in the clientes/polizas/servicios detail pages. */
+function KV({ label, value }: { label: string; value: string | null | undefined }) {
+  return (
+    <div>
+      <div className="kv-label">{label}</div>
+      <div className="kv-value">{value || "—"}</div>
+    </div>
+  );
+}
+
+/**
+ * Step progress for a running migration.
+ *
+ * Only REIMPORT and SYNC report steps; BACKUP and RESTORE are a single
+ * mysqldump, so they render nothing here rather than a made-up bar — the
+ * spinner in the heading already says "working".
+ *
+ * The safety backup runs before the migration, so `progress` is null for the
+ * first stretch of every REIMPORT. That phase is named explicitly instead of
+ * showing 0%, which would read as "stuck".
+ */
+function JobProgressBar({ job }: { job: OpsJob }) {
+  const running = job.status === "RUNNING";
+  const p = job.progress;
+
+  if (!p) {
+    if (!running) return null;
+    return (
+      <p className="inline-form-note" style={{ marginTop: 8 }}>
+        Respaldo de seguridad previo…
+      </p>
+    );
+  }
+
+  return (
+    <div style={{ marginTop: 10, marginBottom: 4 }}>
+      <div
+        className="row-actions"
+        style={{ justifyContent: "space-between", marginBottom: 6 }}
+      >
+        <span className="inline-form-note" style={{ margin: 0 }}>
+          Paso {p.step} de {p.total} — {p.name}
+        </span>
+        <span className="inline-form-note" style={{ margin: 0 }}>
+          {p.percent}%
+        </span>
+      </div>
+      <div
+        role="progressbar"
+        aria-valuenow={p.percent}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-label={`Paso ${p.step} de ${p.total}`}
+        style={{
+          height: 6,
+          borderRadius: 999,
+          background: "var(--line)",
+          overflow: "hidden",
+        }}
+      >
+        <div
+          style={{
+            width: `${p.percent}%`,
+            height: "100%",
+            borderRadius: 999,
+            transition: "width 400ms ease",
+            background:
+              job.status === "FAILED"
+                ? "var(--negative)"
+                : "var(--positive)",
+          }}
+        />
+      </div>
+    </div>
+  );
+}

apps/web/src/app/polizas/[id]/page.tsx

@@ -26,7 +26,13 @@ import {
   premiumHeadline,
   SIN_NOMBRE,
 } from "@/lib/labels";
-import type { AdjusterRow, Installment, PolicyDetail } from "@/lib/types";
+import {
+  PAYMENT_FREQUENCY_LABELS,
+  type AdjusterRow,
+  type Installment,
+  type PolicyDetail,
+} from "@/lib/types";
+import { formatRate } from "@/lib/premium";
 
 export default function PolizaDetailPage({
   params,
@@ -186,6 +192,10 @@ function ChildrenEditor({
   const INSTALLMENTS: ChildConfig = {
     apiKind: "installments",
     title: "Pagos",
+    // A policy paid in several exhibiciones prices each payment on its own, so
+    // the whole premium breakdown repeats per row — that is the two-row money
+    // block on the Access form. `amount` stays what was actually collected and
+    // is deliberately separate from `total`; they differ by rounding.
     fields: [
       { key: "sequence", label: "Sec.", type: "number" },
       { key: "amount", label: "Monto", type: "number" },
@@ -195,6 +205,12 @@ function ChildrenEditor({
       { key: "paidDate", label: "Pagado", type: "date" },
       { key: "checkNumber", label: "Cheque" },
       { key: "isCash", label: "Efectivo", type: "checkbox" },
+      { key: "netPremium", label: "Prima neta", type: "number" },
+      { key: "surcharge", label: "Recargo", type: "number" },
+      { key: "policyFee", label: "Derecho", type: "number" },
+      { key: "tax", label: "IVA", type: "number" },
+      { key: "total", label: "Prima total", type: "number" },
+      { key: "commission", label: "Comisión", type: "number" },
     ],
   };
   const VEHICLES: ChildConfig = {
@@ -412,15 +428,40 @@ function CondicionesSection({ data }: { data: PolicyDetail }) {
               data.coveragePeriodDays ? `${data.coveragePeriodDays} días` : null
             }
           />
+          <KV
+            label="Forma de pago"
+            value={
+              data.paymentFrequency
+                ? PAYMENT_FREQUENCY_LABELS[data.paymentFrequency]
+                : null
+            }
+          />
           <KV label="Prima neta" value={formatMoney(data.netPremium, cur)} />
+          {/* Only ever set on a policy paid in installments, so showing an
+              empty row on the other 98% would be noise. */}
+          {data.surcharge != null && Number(data.surcharge) !== 0 && (
+            <KV label="Recargo" value={formatMoney(data.surcharge, cur)} />
+          )}
           <KV label="Derecho de póliza" value={formatMoney(data.policyFee, cur)} />
-          <KV label="Comisión" value={formatMoney(data.commission, cur)} />
+          {/* Access never stored IVA — it was a calculated control on the form
-          <KV label="Honorarios" value={formatMoney(data.brokerFee, cur)} />
+              — so every migrated policy reads null here until it is edited. */}
+          {data.tax != null && (
+            <KV
+              label={
+                data.taxRate != null
+                  ? `IVA (${formatRate(Number(data.taxRate))})`
+                  : "IVA"
+              }
+              value={formatMoney(data.tax, cur)}
+            />
+          )}
           {/* The legacy `total` is 0 or null on all but 2 of 2378 policies —
               only show it when it actually carries a figure. */}
           {data.total != null && Number(data.total) > 0 && (
-            <KV label="Total" value={formatMoney(data.total, cur)} />
+            <KV label="Prima total" value={formatMoney(data.total, cur)} />
           )}
+          <KV label="Comisión" value={formatMoney(data.commission, cur)} />
+          <KV label="Honorarios" value={formatMoney(data.brokerFee, cur)} />
           <KV
             label="Liquidación"
             value={
@@ -648,10 +689,79 @@ function SiniestrosSection({ data }: { data: PolicyDetail }) {
 }
 
 /* -------------------------------------------------------- Coberturas */
-/** The legacy tables carry per-line coverage columns the target schema does
+/**
- *  not model; the migration preserved them verbatim in `coveragesJson`. */
+ * `coveragesJson` holds two unrelated shapes and the section renders each on
+ * its own terms:
+ *
+ * - **A Spanish-keyed object** — the legacy per-line coverage columns the
+ *   target schema does not model, preserved verbatim by the migration. Every
+ *   policy imported from Access carries this one.
+ * - **A `ParsedCoverage[]` array** — written by the policy OCR confirm step
+ *   (GMX's coverage table, ANA's numbered risk sections).
+ *
+ * Running the object renderer over the array is what used to happen, and it
+ * produced a row per array index labelled "0", "1", "2" with `[object
+ * Object]` as its value — not a crash, so nothing surfaced it.
+ */
+interface StoredCoverage {
+  risk?: string;
+  insuredAmount?: number | null;
+  deductible?: string | null;
+  lossParticipation?: string | null;
+  premium?: number | null;
+}
+
 function CoberturasSection({ data }: { data: PolicyDetail }) {
-  const entries = Object.entries(data.coveragesJson ?? {}).filter(
+  const raw = data.coveragesJson ?? null;
+
+  if (Array.isArray(raw)) {
+    const rows = (raw as StoredCoverage[]).filter((c) => c && c.risk);
+    if (rows.length === 0) return null;
+    return (
+      <section className="section">
+        <SectionHead rule="seguros" title="Coberturas" count={rows.length} />
+        <div className="card">
+          <div className="tx-scroll">
+            <table className="tx-table">
+              <thead>
+                <tr>
+                  <th>Riesgo</th>
+                  <th className="num">Suma asegurada</th>
+                  <th className="num">Prima</th>
+                  <th>Deducible</th>
+                  <th>Participación</th>
+                </tr>
+              </thead>
+              <tbody>
+                {rows.map((c, i) => (
+                  <tr key={i}>
+                    <td>{c.risk}</td>
+                    <td className="num">
+                      {c.insuredAmount == null
+                        ? "—"
+                        : formatMoney(c.insuredAmount.toString(), data.currency)}
+                    </td>
+                    <td className="num">
+                      {c.premium == null
+                        ? "—"
+                        : formatMoney(c.premium.toString(), data.currency)}
+                    </td>
+                    <td>{c.deductible ?? "—"}</td>
+                    <td>{c.lossParticipation ?? "—"}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+          <div className="section-note" style={{ padding: "0 22px 18px" }}>
+            Coberturas leídas del PDF de la aseguradora.
+          </div>
+        </div>
+      </section>
+    );
+  }
+
+  const entries = Object.entries(raw ?? {}).filter(
     ([, v]) => v !== null && v !== "" && v !== 0,
   );
   if (entries.length === 0) return null;

apps/web/src/app/polizas/captura/page.tsx

@@ -4,7 +4,7 @@ import { AppShell } from "@/components/AppShell";
 import { PolicyCaptura } from "@/components/PolicyCaptura";
 
 /**
- * OCR mode of the policy intake screen. Drops the GMX PDF, walks through
+ * OCR mode of the policy intake screen. Drops the GMX or A.N.A. PDF, walks through
  * per-page review, confirms. Same wrapper as `/polizas/nuevo` (manual)
  * with `initialMode="auto"`, so the tab strip is identical and swapping
  * modes doesn't drop state.

apps/web/src/components/ChildCollection.tsx

@@ -9,6 +9,9 @@ export type FieldDef = {
   type?: "text" | "number" | "date" | "checkbox" | "select";
   options?: { value: string; label: string }[];
   width?: number;
+  /** Numeric granularity. Defaults to money (0.01); a tax rate stored as a
+   *  fraction needs finer, or the browser rejects 0.0825 as off-step. */
+  step?: string;
 };
 
 export type ChildConfig = {
@@ -158,7 +161,7 @@ export function ChildCollection({
                 <input
                   className="input"
                   type={f.type === "number" ? "number" : f.type === "date" ? "date" : "text"}
-                  step={f.type === "number" ? "0.01" : undefined}
+                  step={f.type === "number" ? f.step ?? "0.01" : undefined}
                   value={String(values[f.key] ?? "")}
                   onChange={(e) => setValues({ ...values, [f.key]: e.target.value })}
                 />

apps/web/src/components/PolicyCaptura.tsx

@@ -12,7 +12,7 @@ import { useCan } from "@/lib/abilities";
  * two ways in:
  *
  * - **manual** — `PolicyForm` keys every field by hand.
- * - **auto** — `PolicyOcrIntake` uploads a GMX PDF, OCR proposes the
+ * - **auto** — `PolicyOcrIntake` uploads a GMX or A.N.A. PDF, OCR proposes the
  *   policy, a human still confirms.
  *
  * Both end at the same place (a `Policy` row on a customer's file) so they
@@ -28,7 +28,7 @@ export type PolicyCaptureMode = "manual" | "auto";
 const MODE_HINT: Record<PolicyCaptureMode, string> = {
   manual:
     "Captura cada campo a mano. Use esta opción cuando la póliza llega en papel, en un correo sin PDF legible, o cuando hay que revisar cada dato.",
-  auto: "Suelte el PDF descargado del portal de GMX y el sistema propondrá los campos. Nada se registra sin tu confirmación.",
+  auto: "Suelte el PDF descargado del portal de GMX o de A.N.A. y el sistema propondrá los campos. Nada se registra sin tu confirmación.",
 };
 
 export function PolicyCaptura({ initialMode = "manual" }: { initialMode?: PolicyCaptureMode }) {

apps/web/src/components/PolicyForm.tsx

@@ -4,12 +4,22 @@ import { useEffect, useState } from "react";
 import { useRouter } from "next/navigation";
 import { CustomerPicker } from "@/components/CustomerPicker";
 import { createPolicy, getLookups, updatePolicy } from "@/lib/api";
-import type {
+import {
-  Currency,
+  PAYMENT_FREQUENCY_LABELS,
-  LookupsResponse,
+  type Currency,
-  PolicyDetail,
+  type LookupsResponse,
-  PolicyInput,
+  type PaymentFrequency,
+  type PolicyDetail,
+  type PolicyInput,
 } from "@/lib/types";
+import {
+  computeTax,
+  computeTotal,
+  formatRate,
+  resolveTaxRate,
+  surchargeApplies,
+  taxableBase,
+} from "@/lib/premium";
 
 function toDateInput(v: string | null | undefined): string {
   if (!v) return "";
@@ -36,9 +46,16 @@ type V = {
   policyFrom: string;
   policyTo: string;
   netPremium: string;
+  surcharge: string;
   policyFee: string;
   brokerFee: string;
   commission: string;
+  /** Blank means "use the computed figure". Only ever holds a value once the
+   *  operator overrides it, so a later change to prima neta keeps flowing
+   *  through instead of being frozen by a value the form itself wrote. */
+  tax: string;
+  total: string;
+  paymentFrequency: PaymentFrequency | "";
   currency: Currency;
   liquidated: boolean;
   liquidationNumber: string;
@@ -58,9 +75,13 @@ function initial(p?: PolicyDetail): V {
     policyFrom: toDateInput(p?.policyFrom),
     policyTo: toDateInput(p?.policyTo),
     netPremium: p?.netPremium != null ? String(p.netPremium) : "",
+    surcharge: p?.surcharge != null ? String(p.surcharge) : "",
     policyFee: p?.policyFee != null ? String(p.policyFee) : "",
     brokerFee: p?.brokerFee != null ? String(p.brokerFee) : "",
     commission: p?.commission != null ? String(p.commission) : "",
+    tax: p?.tax != null ? String(p.tax) : "",
+    total: p?.total != null ? String(p.total) : "",
+    paymentFrequency: p?.paymentFrequency ?? "",
     currency: (p?.currency as Currency) ?? "MXN",
     liquidated: p?.liquidated ?? false,
     liquidationNumber: p?.liquidationNumber ?? "",
@@ -101,6 +122,27 @@ export function PolicyForm({
     setV((p) => ({ ...p, [k]: val }));
   }
 
+  // IVA and Total are the only two figures the form derives. Everything else,
+  // the recargo included, is keyed by hand — the carrier quotes the financing
+  // charge, we do not compute it.
+  const selectedType = lookups?.types.find((t) => t.id === v.policyTypeId);
+  const taxRate = resolveTaxRate(policy?.taxRate, selectedType?.taxRate);
+  const parts = {
+    netPremium: v.netPremium,
+    // A recargo on an annual policy is a data-entry mistake, so it is dropped
+    // from the arithmetic as well as disabled in the UI. Otherwise switching
+    // ANNUAL after typing one would leave it silently inflating the IVA.
+    surcharge: surchargeApplies(v.paymentFrequency || null) ? v.surcharge : "",
+    policyFee: v.policyFee,
+  };
+  const computedTax = computeTax(parts, taxRate);
+  const computedTotal = computeTotal(parts, taxRate);
+  // Blank field = take the computed figure. A typed one wins, so staff can key
+  // the carrier's rounding verbatim when it disagrees with ours by a centavo.
+  const effectiveTax = v.tax.trim() === "" ? computedTax : Number(v.tax);
+  const effectiveTotal = v.total.trim() === "" ? computedTotal : Number(v.total);
+  const showSurcharge = surchargeApplies(v.paymentFrequency || null);
+
   async function submit(e: React.FormEvent) {
     e.preventDefault();
     if (!customerId) {
@@ -118,9 +160,17 @@ export function PolicyForm({
       policyFrom: s(v.policyFrom),
       policyTo: s(v.policyTo),
       netPremium: numOrUndef(v.netPremium),
+      surcharge: showSurcharge ? numOrUndef(v.surcharge) : undefined,
       policyFee: numOrUndef(v.policyFee),
       brokerFee: numOrUndef(v.brokerFee),
       commission: numOrUndef(v.commission),
+      // The derived figures are persisted, not recomputed on read: the printed
+      // policy is the record of truth and a later rate change must not silently
+      // restate what was issued. `taxRate` rides along for the same reason.
+      tax: Number.isFinite(effectiveTax) ? effectiveTax : undefined,
+      taxRate,
+      total: Number.isFinite(effectiveTotal) ? effectiveTotal : undefined,
+      paymentFrequency: v.paymentFrequency || undefined,
       currency: v.currency,
       liquidated: v.liquidated,
       liquidationNumber: s(v.liquidationNumber),
@@ -208,7 +258,7 @@ export function PolicyForm({
       </div>
 
       <div className="card" style={{ padding: 20, marginBottom: 16 }}>
-        <h2 className="section-title" style={{ marginBottom: 14 }}>Vigencia y prima</h2>
+        <h2 className="section-title" style={{ marginBottom: 14 }}>Vigencia</h2>
         <div className="form-grid">
           <label className="field">
             <span className="field-label">Emisión</span>
@@ -225,21 +275,84 @@ export function PolicyForm({
             <input className="input" type="date" value={v.policyTo}
               onChange={(e) => set("policyTo", e.target.value)} />
           </label>
+          <label className="field">
+            <span className="field-label">Forma de pago</span>
+            <select className="select" value={v.paymentFrequency}
+              onChange={(e) =>
+                set("paymentFrequency", e.target.value as PaymentFrequency | "")
+              }>
+              <option value="">—</option>
+              {(
+                Object.keys(PAYMENT_FREQUENCY_LABELS) as PaymentFrequency[]
+              ).map((f) => (
+                <option key={f} value={f}>{PAYMENT_FREQUENCY_LABELS[f]}</option>
+              ))}
+            </select>
+          </label>
+        </div>
+      </div>
+
+      <div className="card" style={{ padding: 20, marginBottom: 16 }}>
+        <h2 className="section-title" style={{ marginBottom: 4 }}>Primas</h2>
+        <p className="muted" style={{ fontSize: 12, marginBottom: 14 }}>
+          IVA y prima total se calculan solos sobre (prima neta + recargo +
+          derecho de póliza). Puede sobrescribirlos si la póliza impresa
+          redondea distinto.
+        </p>
+        <div className="form-grid">
           <label className="field">
             <span className="field-label">Prima neta</span>
             <input className="input" type="number" step="0.01" value={v.netPremium}
               onChange={(e) => set("netPremium", e.target.value)} />
           </label>
+          <label className="field">
+            <span className="field-label">Recargo</span>
+            <input className="input" type="number" step="0.01" value={v.surcharge}
+              disabled={!showSurcharge}
+              onChange={(e) => set("surcharge", e.target.value)} />
+            <span className="field-hint">
+              {showSurcharge
+                ? "Lo cotiza la aseguradora — se captura a mano."
+                : "No aplica en pago anual ni de contado."}
+            </span>
+          </label>
           <label className="field">
             <span className="field-label">Derecho de póliza</span>
             <input className="input" type="number" step="0.01" value={v.policyFee}
               onChange={(e) => set("policyFee", e.target.value)} />
           </label>
+          <label className="field">
+            <span className="field-label">IVA ({formatRate(taxRate)})</span>
+            <input className="input" type="number" step="0.01"
+              placeholder={computedTax.toFixed(2)} value={v.tax}
+              onChange={(e) => set("tax", e.target.value)} />
+            <span className="field-hint">
+              Calculado: {computedTax.toFixed(2)} sobre base{" "}
+              {taxableBase(parts).toFixed(2)}
+              {selectedType?.taxRate == null &&
+                policy?.taxRate == null &&
+                " · tasa por omisión, configúrela en Catálogos"}
+            </span>
+          </label>
+          <label className="field">
+            <span className="field-label">Prima total</span>
+            <input className="input" type="number" step="0.01"
+              placeholder={computedTotal.toFixed(2)} value={v.total}
+              onChange={(e) => set("total", e.target.value)} />
+            <span className="field-hint">
+              Calculado: {computedTotal.toFixed(2)}
+            </span>
+          </label>
           <label className="field">
             <span className="field-label">Comisión</span>
             <input className="input" type="number" step="0.01" value={v.commission}
               onChange={(e) => set("commission", e.target.value)} />
           </label>
+          <label className="field">
+            <span className="field-label">Honorarios</span>
+            <input className="input" type="number" step="0.01" value={v.brokerFee}
+              onChange={(e) => set("brokerFee", e.target.value)} />
+          </label>
         </div>
       </div>
 

apps/web/src/components/PolicyOcrIntake.tsx

@@ -13,9 +13,12 @@ import type { PolicyOcrBatch, PolicyOcrBatchStatus } from "@/lib/types";
 
 /**
  * Insurance OCR intake — mirror of StatementIntake, scoped to the insurance
- * side. Today the only provider is GMX; the parser dispatches on a brand
+ * side. GMX and A.N.A. today; the parser dispatches on a brand wordmark
- * wordmark (`Grupo Mexicano de Seguros` / `gmx.com.mx` / the GMX letterhead)
+ * (`Grupo Mexicano de Seguros` / `gmx.com.mx`, `A.N.A. Compañía de Seguros` /
- * and a new portal only needs a new BRAND entry plus a parser file.
+ * `anaseguros.com.mx`) and a new portal only needs a new BRAND entry plus a
+ * parser file. The uploader is never asked which provider a file came from —
+ * a batch may mix them, and the pipeline labels the batch from what the
+ * parsers actually claimed.
  *
  * Lives inside the `Pólizas` page rather than a top-level route because it
  * is one mode of one job (staff uploading whatever PDFs the office has on
@@ -102,8 +105,8 @@ export function PolicyOcrIntake() {
           <div className="state-box">Cargando…</div>
         ) : batches.length === 0 ? (
           <div className="state-box">
-            Todavía no hay lotes de pólizas. Descargue el certificado del portal
+            Todavía no hay lotes de pólizas. Descargue la póliza del portal de
-            de GMX y suéltelo arriba.
+            GMX o de A.N.A. y suéltela arriba.
           </div>
         ) : (
           <div className="tx-scroll">
@@ -183,14 +186,14 @@ function UploadCard({ onDone }: { onDone: () => void }) {
   return (
     <section className="card" style={{ padding: 16 }}>
       <h2 className="section-title" style={{ marginTop: 0 }}>
-        Subir PDFs de pólizas (GMX)
+        Subir PDFs de pólizas (GMX / A.N.A.)
       </h2>
       <div className="inline-form" style={{ flexWrap: "wrap", gap: 12 }}>
         <label>
           <span className="page-sub">Referencia (opcional)</span>
           <input
             className="input"
-            placeholder="ej. GMX julio 2026"
+            placeholder="ej. ANA agosto 2026"
             value={label}
             onChange={(e) => setLabel(e.target.value)}
           />

apps/web/src/components/PolicyOcrReview.tsx

@@ -21,6 +21,7 @@ import type {
   PolicyOcrBatchDetail,
   PolicyOcrConfirmDocument,
   PolicyOcrCoverage,
+  PolicyOcrCustomerSuggestion,
   PolicyOcrDocument,
   PolicyOcrReviewInput,
 } from "@/lib/types";
@@ -180,8 +181,11 @@ export function PolicyOcrReview({ id }: { id: string }) {
             {STATUS_LABEL[batch.status] ?? batch.status}
           </p>
         </div>
-        <Link className="btn btn-ghost" href="/polizas">
+        {/* Back to the capture screen this batch was uploaded from, not to
-          Volver a pólizas
+            the policy list — same as the statement review screen, which
+            returns to /recibos. */}
+        <Link className="btn btn-ghost" href="/polizas/captura">
+          Volver a captura
         </Link>
       </header>
 
@@ -272,8 +276,11 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
     policyDate: doc.extractedPolicyDate?.slice(0, 10) ?? "",
     currency: doc.extractedCurrency ?? "USD",
     netPremium: doc.extractedNetPremium ?? "",
+    policyFee: doc.extractedPolicyFee ?? "",
+    tax: doc.extractedTax ?? "",
     total: doc.extractedTotal ?? "",
     premiumPayment: doc.extractedPremiumPayment ?? "",
+    coveragePeriodDays: doc.extractedCoveragePeriodDays?.toString() ?? "",
     postPremium: doc.extractedNetPremium != null && Number(doc.extractedNetPremium) > 0,
   });
   const [customerId, setCustomerId] = useState(
@@ -309,8 +316,11 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
         policyDate: v.policyDate || undefined,
         currency,
         netPremium: numOrUndef(v.netPremium),
+        policyFee: numOrUndef(v.policyFee),
+        tax: numOrUndef(v.tax),
         total: numOrUndef(v.total),
         premiumPayment: trimOrUndef(v.premiumPayment),
+        coveragePeriodDays: numOrUndef(v.coveragePeriodDays),
         matchedPolicyId: policyId || undefined,
         matchedCustomerId: !policyId && customerId ? customerId : undefined,
         forceConfirm: true,
@@ -330,8 +340,11 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
         policyDate: reviewInput.policyDate,
         currency: (currency as "MXN" | "USD" | "EUR" | undefined) ?? undefined,
         netPremium: reviewInput.netPremium,
+        policyFee: reviewInput.policyFee,
+        tax: reviewInput.tax,
         total: reviewInput.total,
         premiumPayment: reviewInput.premiumPayment,
+        coveragePeriodDays: reviewInput.coveragePeriodDays,
         coveragesJson: (doc.extractedCoveragesJson ?? undefined) as
           | PolicyOcrCoverage[]
           | undefined,
@@ -348,18 +361,27 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
   const locked = doc.status === "POSTED" || doc.status === "REJECTED";
   const matchedExisting = !!doc.matchedPolicy;
   const candidates = doc.matchCandidates ?? [];
+  const suggestions: PolicyOcrCustomerSuggestion[] = doc.customerSuggestions ?? [];
 
   return (
     <article className="card" style={{ padding: 16 }}>
       <header className="row" style={{ gap: 12, alignItems: "center" }}>
         <span className="tag">{STATUS_LABEL[doc.status] ?? doc.status}</span>
         <span className="page-sub">Página {doc.pageNumber}</span>
-        {doc.extractedPolicyNumber && (
+        {/* No hand-rolled separators or margins here: `.row` is a flex
-          <strong style={{ marginLeft: 8 }}>{doc.extractedPolicyNumber}</strong>
+            container and its gap does the spacing. A literal "· " would leave
-        )}
+            a dot floating in that gap. */}
+        {doc.extractedPolicyNumber && <strong>{doc.extractedPolicyNumber}</strong>}
         {doc.extractedInsuredName && (
-          <span className="page-sub">· {doc.extractedInsuredName}</span>
+          <span className="page-sub">{doc.extractedInsuredName}</span>
         )}
+        {/* Read-only: the parser names the type, the confirm step resolves it
+            to a policy_types row. Reassigning it is the policy screen's job,
+            where the full picker already lives. */}
+        {doc.extractedPolicyTypeName && (
+          <span className="tag">{doc.extractedPolicyTypeName}</span>
+        )}
+        {doc.provider && <span className="tag">{doc.provider}</span>}
       </header>
 
       <div className="doc-detail">
@@ -454,6 +476,17 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
                 onChange={(e) => set("policyDate", e.target.value)}
               />
             </Field>
+            {/* ANA sells 3- and 4-day tourist policies; left blank the
+                póliza keeps the 365-day default. */}
+            <Field label="Días de vigencia">
+              <input
+                className="input"
+                type="number"
+                min={1}
+                value={v.coveragePeriodDays}
+                onChange={(e) => set("coveragePeriodDays", e.target.value)}
+              />
+            </Field>
             <Field label="Moneda">
               <select
                 className="input select"
@@ -474,7 +507,25 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
                 onChange={(e) => set("netPremium", e.target.value)}
               />
             </Field>
-            <Field label="Total">
+            <Field label="Derecho de póliza">
+              <input
+                className="input"
+                type="number"
+                step="0.01"
+                value={v.policyFee}
+                onChange={(e) => set("policyFee", e.target.value)}
+              />
+            </Field>
+            <Field label="IVA">
+              <input
+                className="input"
+                type="number"
+                step="0.01"
+                value={v.tax}
+                onChange={(e) => set("tax", e.target.value)}
+              />
+            </Field>
+            <Field label="Prima total">
               <input
                 className="input"
                 type="number"
@@ -523,6 +574,7 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
                   <tr>
                     <th>Riesgo</th>
                     <th className="num">Suma</th>
+                    <th className="num">Prima</th>
                     <th>Deducible</th>
                     <th>Participación</th>
                   </tr>
@@ -534,6 +586,14 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
                       <td className="num">
                         {formatMoney(c.insuredAmount?.toString() ?? null, v.currency)}
                       </td>
+                      {/* ANA's add-on sections print what the coverage COST
+                          where the others print what it pays. Kept in its own
+                          column so the two are never added together. */}
+                      <td className="num">
+                        {c.premium == null
+                          ? "—"
+                          : formatMoney(c.premium.toString(), v.currency)}
+                      </td>
                       <td>{c.deductible ?? "—"}</td>
                       <td>{c.lossParticipation ?? "—"}</td>
                     </tr>
@@ -543,6 +603,66 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
             </details>
           )}
 
+          {/*
+           * Vehicles and named drivers are read-only here: they are written
+           * as their own Vehicle / InsuredDriver rows on confirm, and the
+           * policy screen is where they get edited. Showing them is what
+           * lets a reviewer catch a misread VIN before it is applied.
+           */}
+          {doc.extractedVehiclesJson && doc.extractedVehiclesJson.length > 0 && (
+            <details>
+              <summary>Unidades ({doc.extractedVehiclesJson.length})</summary>
+              <table className="tx-table" style={{ marginTop: 8 }}>
+                <thead>
+                  <tr>
+                    <th>Tipo</th>
+                    <th>Año</th>
+                    <th>Marca</th>
+                    <th>Carrocería</th>
+                    <th>Serie</th>
+                    <th>Placas</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {doc.extractedVehiclesJson.map((veh, i) => (
+                    <tr key={i}>
+                      <td>{veh.item}</td>
+                      <td>{veh.modelYear ?? "—"}</td>
+                      <td>{veh.make ?? "—"}</td>
+                      <td>{veh.bodyType ?? "—"}</td>
+                      <td>{veh.vinNumber ?? "—"}</td>
+                      <td>{veh.licensePlate ?? "—"}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </details>
+          )}
+
+          {doc.extractedDriversJson && doc.extractedDriversJson.length > 0 && (
+            <details>
+              <summary>Conductores ({doc.extractedDriversJson.length})</summary>
+              <table className="tx-table" style={{ marginTop: 8 }}>
+                <thead>
+                  <tr>
+                    <th>Nombre</th>
+                    <th>Licencia</th>
+                    <th>Teléfono</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {doc.extractedDriversJson.map((d, i) => (
+                    <tr key={i}>
+                      <td>{d.fullName}</td>
+                      <td>{d.licenseNumber ?? "—"}</td>
+                      <td>{d.phone ?? "—"}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </details>
+          )}
+
           {candidates.length > 1 && (
             <Field label="Póliza destino">
               <select
@@ -580,6 +700,34 @@ function DocumentRow({ doc, customerIndex, canReview, onSave, onReject }: Docume
             </Field>
           )}
 
+          {/*
+           * Name suggestions, never a preselection. The office writes
+           * customers surname-first and carriers print them given-name-first,
+           * so without this the reviewer retypes a name the parser already
+           * read. One click fills the picker above; nothing is chosen until
+           * they click. Kept outside the <Field> label — a label must not
+           * wrap other interactive controls.
+           */}
+          {!policyId && !customerId && !locked && canReview && suggestions.length > 0 && (
+            <div className="row" style={{ gap: 8, flexWrap: "wrap" }}>
+              <span className="page-sub">Sugerencias por nombre:</span>
+              {suggestions.map((s) => (
+                <button
+                  key={s.customerId}
+                  type="button"
+                  className="btn btn-ghost btn-sm"
+                  onClick={() => {
+                    setCustomerId(s.customerId);
+                    setCustomerName(s.customerName);
+                  }}
+                >
+                  {s.customerName}
+                  {s.tier === "PARTIAL" && <span className="page-sub"> · parcial</span>}
+                </button>
+              ))}
+            </div>
+          )}
+
           <label className="field">
             <input
               type="checkbox"

apps/web/src/lib/api.ts

@@ -59,6 +59,8 @@ import type {
   LookupsResponse,
   OpsJob,
   OpsJobKind,
+  ReplicationStatus,
+  VerifyResult,
   IngestFile,
   BackupFile,
   PropertyDetail,
@@ -80,15 +82,26 @@ import type {
   UserRow,
 } from "./types";
 
-// Resolve the API origin at runtime, not build time. In the browser it comes
+// Resolve the API origin at runtime, not build time — so one built image serves
-// from window.__API_ORIGIN__, injected server-side by the root layout from the
+// any deployment and the app follows the box when it moves (tailnet today,
-// deploy .env (API_ORIGIN) — so one built image serves any deployment. On the
+// 192.168.1.x office LAN later) with no config change.
-// server (SSR) read process.env directly. NEXT_PUBLIC_API_ORIGIN stays as the
+//
-// dev/build fallback.
+// In the browser, derive the origin from the page's own location, the way a PHP
+// app would. An explicit API_ORIGIN (injected as window.__API_ORIGIN__ by the
+// root layout) still wins when a deployment genuinely splits the two hosts.
+// On the server (SSR) read process.env directly — a derived origin is
+// browser-only, and "/api" is not fetchable server-side.
 function resolveApiOrigin(): string {
   if (typeof window !== "undefined") {
     const injected = (window as { __API_ORIGIN__?: string }).__API_ORIGIN__;
     if (injected) return injected;
+    const { protocol, hostname } = window.location;
+    // Over TLS the API must share the page's origin or the browser blocks the
+    // call as mixed active content. The reverse proxy maps /api to the API.
+    if (protocol === "https:") return "/api";
+    // Plain HTTP: same host, API port. 3001 is the port the API container
+    // publishes everywhere (deploy/galactus/jorgecuadros-app.compose.yml).
+    return `http://${hostname}:3001`;
   }
   return (
     process.env.API_ORIGIN ??
@@ -231,6 +244,20 @@ export function restoreCustomer(id: string): Promise<CustomerDetail> {
   return apiFetch<CustomerDetail>(`/customers/${id}/restore`, { method: "POST" });
 }
 
+export interface NumidAllocation {
+  numid: string;
+  /** "existing" when the customer already had one — the call is idempotent. */
+  origin: "existing" | "new" | "recycled";
+  previousCustomerId?: string;
+}
+
+/** Give a customer the portal NUMid they log in to my.jorgecuadros.com with. */
+export function grantPortalAccess(id: string): Promise<NumidAllocation> {
+  return apiFetch<NumidAllocation>(`/customers/${id}/portal-access`, {
+    method: "POST",
+  });
+}
+
 /* ------------------------------------------------------ Policies module */
 
 /** Renewal horizon in days, shared by the list, stats and detail calls so the
@@ -588,8 +615,13 @@ export function getBillingFacets(): Promise<BillingFacets> {
   return apiFetch<BillingFacets>("/billing/facets");
 }
 
-export function getStatement(customerId: string): Promise<Statement> {
+/** `year` omitted reads the current period; earlier years come from an archive. */
-  return apiFetch<Statement>(`/billing/customers/${customerId}`);
+export function getStatement(
+  customerId: string,
+  year?: number,
+): Promise<Statement> {
+  const q = year === undefined ? "" : `?year=${year}`;
+  return apiFetch<Statement>(`/billing/customers/${customerId}${q}`);
 }
 
 /** Append a new ledger movement. Booked movements are never edited — fix
@@ -939,6 +971,28 @@ export function deleteBackup(name: string): Promise<unknown> {
   return apiFetch(`/ops/backups/${encodeURIComponent(name)}`, { method: "DELETE" });
 }
 
+/**
+ * Health of the read replica my.jorgecuadros.com serves customers from.
+ *
+ * A stopped replica does not error — it answers with stale balances — so this
+ * is the only place the failure is visible.
+ */
+export function getReplicationStatus(): Promise<ReplicationStatus> {
+  return apiFetch<ReplicationStatus>("/ops/replication");
+}
+
+/**
+ * Compare every customer-visible table against the master, row by row.
+ *
+ * Slow by nature — it is a full scan of both servers — so it is a button, not
+ * part of the poll. Answers the question replication status cannot: GTIDs prove
+ * the replica applied everything the master sent, not that nothing else changed
+ * the rows here.
+ */
+export function verifyReplication(): Promise<VerifyResult> {
+  return apiFetch<VerifyResult>("/ops/replication/verify", { method: "POST" });
+}
+
 export function listOpsJobs(): Promise<OpsJob[]> {
   return apiFetch<OpsJob[]>("/ops/jobs");
 }
@@ -948,10 +1002,16 @@ export function getOpsJob(id: string): Promise<OpsJob> {
 }
 
 /** Start a mutating op. `file` is required for RESTORE. 409 if one is running. */
-export function startOpsJob(kind: OpsJobKind, file?: string): Promise<OpsJob> {
+/** `forceFull` applies to REIMPORT only: proceed even though the rebuild
+ *  deletes rows that exist only in the platform. */
+export function startOpsJob(
+  kind: OpsJobKind,
+  file?: string,
+  forceFull?: boolean,
+): Promise<OpsJob> {
   return apiFetch<OpsJob>("/ops/jobs", {
     method: "POST",
-    body: JSON.stringify({ kind, file }),
+    body: JSON.stringify({ kind, file, forceFull }),
   });
 }
 
@@ -1377,7 +1437,7 @@ export function statementPageUrl(documentId: string): string {
   return `${API_ORIGIN}/statements/documents/${documentId}/page`;
 }
 
-/* ----------------------------------------------------- Policy OCR (GMX) */
+/* ----------------------------------------------- Policy OCR (GMX / ANA) */
 
 export function getPolicyOcrStatus(): Promise<{
   ocrAvailable: boolean;

apps/web/src/lib/premium.ts

@@ -0,0 +1,79 @@
+import type { PaymentFrequency } from "./types";
+
+/**
+ * Client-side twin of apps/api/src/policies/premium.ts. Duplicated rather than
+ * shared because the API and the web app do not share a package today, and
+ * both need it: the form computes IVA and Total live as the operator types,
+ * the API stores what it is sent.
+ *
+ *   base  = prima neta + recargo + derecho de póliza
+ *   IVA   = round(base * tasa)
+ *   Total = base + IVA
+ *
+ * The recargo is inside the taxable base — that is what reconciles the Access
+ * books (policy 7006785 prints IVA 52.03 on 610.86 + 8.55 + 31.00; leaving the
+ * recargo out gives 51.35, which matches nothing on the page).
+ */
+
+/** Applied when neither the policy nor its type carries a rate. The single
+ *  row both legacy IMPUESTOS tables held. */
+export const DEFAULT_TAX_RATE = 0.08;
+
+/** Paying in more than one exhibición is what earns a recargo. A null
+ *  frequency (every migrated policy) is treated as "unknown, allow it": the
+ *  legacy recargo figures are real and hiding the field would hide them. */
+export function surchargeApplies(
+  frequency: PaymentFrequency | null | undefined,
+): boolean {
+  return frequency !== "ANNUAL" && frequency !== "SINGLE";
+}
+
+export function num(v: string | number | null | undefined): number {
+  if (v === null || v === undefined || v === "") return 0;
+  const n = typeof v === "number" ? v : Number(String(v).trim());
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** Half-up to cents, matching how the printed policy rounds. */
+export function round2(n: number): number {
+  return Math.round((n + Number.EPSILON) * 100) / 100;
+}
+
+export interface PremiumParts {
+  netPremium: string | number | null | undefined;
+  surcharge: string | number | null | undefined;
+  policyFee: string | number | null | undefined;
+}
+
+export function taxableBase(p: PremiumParts): number {
+  return round2(num(p.netPremium) + num(p.surcharge) + num(p.policyFee));
+}
+
+export function computeTax(p: PremiumParts, rate: number): number {
+  return round2(taxableBase(p) * rate);
+}
+
+export function computeTotal(p: PremiumParts, rate: number): number {
+  return round2(taxableBase(p) + computeTax(p, rate));
+}
+
+/** Rate ladder: what the policy was issued at, else its line of business, else
+ *  the default. Keeps an old policy reading back at its original rate after
+ *  somebody edits the catalog. */
+export function resolveTaxRate(
+  policyRate: string | number | null | undefined,
+  policyTypeRate: string | number | null | undefined,
+): number {
+  for (const candidate of [policyRate, policyTypeRate]) {
+    if (candidate === null || candidate === undefined || candidate === "") continue;
+    const n = Number(candidate);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  return DEFAULT_TAX_RATE;
+}
+
+/** 0.08 -> "8%". Rates are stored as fractions but read as percentages. */
+export function formatRate(rate: number): string {
+  const pct = round2(rate * 100);
+  return `${pct}%`;
+}

apps/web/src/lib/types.ts

@@ -3,12 +3,31 @@
 
 export type Currency = "USD" | "MXN";
 
+/** How the premium is split into payments. Anything other than ANNUAL/SINGLE
+ *  is what earns a recargo. Null on every migrated policy — the original ETL
+ *  dropped Access's FORMA PAGO column entirely. */
+export type PaymentFrequency =
+  | "ANNUAL"
+  | "SEMIANNUAL"
+  | "QUARTERLY"
+  | "MONTHLY"
+  | "SINGLE";
+
+export const PAYMENT_FREQUENCY_LABELS: Record<PaymentFrequency, string> = {
+  ANNUAL: "Anual",
+  SEMIANNUAL: "Semestral",
+  QUARTERLY: "Trimestral",
+  MONTHLY: "Mensual",
+  SINGLE: "Contado",
+};
+
 export type Role = "ADMIN" | "MANAGER" | "STAFF" | "VIEWER";
 
 export type Ability =
   | "customer:create"
   | "customer:update"
   | "customer:delete"
+  | "customer:portal-access"
   | "policy:create"
   | "policy:update"
   | "policy:delete"
@@ -61,6 +80,14 @@ export interface UserRow {
 export type OpsJobKind = "BACKUP" | "RESTORE" | "REIMPORT" | "SYNC";
 export type OpsJobStatus = "RUNNING" | "SUCCESS" | "FAILED";
 
+/** Derived from the job log by the API; null for jobs with no step markers. */
+export interface JobProgress {
+  step: number;
+  total: number;
+  name: string;
+  percent: number;
+}
+
 export interface OpsJob {
   id: string;
   kind: OpsJobKind;
@@ -70,6 +97,93 @@ export interface OpsJob {
   createdById: string | null;
   startedAt: string;
   finishedAt: string | null;
+  /** Only present on getOpsJob (the polled endpoint), not on the list. */
+  progress?: JobProgress | null;
+}
+
+/**
+ * Health of the MySQL read replica that my.jorgecuadros.com queries.
+ *
+ * `secondsBehind` is null whenever MySQL reports NULL, which it does when
+ * EITHER thread is down — so null means "unknown", never "up to date". Read
+ * `healthy`/`problem` rather than inferring health from the lag.
+ */
+export interface ReplicationStatus {
+  configured: boolean;
+  healthy: boolean;
+  host: string | null;
+  ioRunning: string | null;
+  sqlRunning: string | null;
+  secondsBehind: number | null;
+  lastIoError: string | null;
+  lastSqlError: string | null;
+  sourceHost: string | null;
+  apply: ApplyProgress | null;
+  drift: GtidDrift | null;
+  problem: string | null;
+  checkedAt: string;
+}
+
+/**
+ * Executed-history gap between master and replica, in transactions.
+ *
+ * The only field on the card that is not self-reported by the replica, and the
+ * only one that catches a silently disconnected I/O thread: with no incoming
+ * events, `secondsBehind` reads 0 because there is nothing to measure staleness
+ * against, so a dead link looks perfectly current. This number grows instead.
+ *
+ * Null when the master could not be reached — "unknown" must not render as
+ * "identical".
+ */
+export interface GtidDrift {
+  missingTransactions: number;
+  missingGtidSet: string | null;
+  /**
+   * Transactions written on the replica under its own server UUID, which exist
+   * nowhere on the master. Non-zero is expected — restoring the seed dump
+   * executed its statements locally — and harmless while nothing replicates
+   * from this node.
+   */
+  localTransactions: number;
+}
+
+/** One table compared on both sides of the link. */
+export interface TableFingerprint {
+  table: string;
+  masterRows: number;
+  replicaRows: number;
+  masterChecksum: string;
+  replicaChecksum: string;
+  matches: boolean;
+}
+
+export interface VerifyResult {
+  identical: boolean;
+  tables: TableFingerprint[];
+  problem: string | null;
+  checkedAt: string;
+  elapsedMs: number;
+}
+
+/**
+ * Relay-log apply progress, in source binlog bytes.
+ *
+ * Answers "is it moving?" when `secondsBehind` cannot: the lag counter sits
+ * still while the SQL thread works through one large transaction, but the
+ * backlog visibly shrinks. `backlogBytes === 0` is the only reading that means
+ * caught up — `percent` deliberately stops at 99.99 while bytes remain.
+ *
+ * Null fields when the two threads are on different source binlog files
+ * (`sameFile === false`), because the positions are then not comparable.
+ */
+export interface ApplyProgress {
+  sourceLogFile: string | null;
+  readPos: number;
+  relayLogFile: string | null;
+  execPos: number;
+  sameFile: boolean;
+  backlogBytes: number | null;
+  percent: number | null;
 }
 
 /** One of the four legacy Access files expected in the ingest folder. */
@@ -78,6 +192,8 @@ export interface IngestFile {
   present: boolean;
   size: number | null;
   modifiedAt: string | null;
+  /** Year of a prior-period archive (`2025.accdb`); null on the four fixed sources. */
+  periodYear: number | null;
 }
 
 export interface BackupFile {
@@ -193,6 +309,16 @@ export interface Installment {
   paidDate: string | null;
   checkNumber: string | null;
   isCash: boolean;
+  /** Per-payment premium breakdown — a policy paid in several exhibiciones
+   *  prices each one separately. `amount` is what was actually collected and
+   *  can differ from `total` by rounding; it is not derived from these. */
+  netPremium: string | null;
+  surcharge: string | null;
+  policyFee: string | null;
+  tax: string | null;
+  taxRate: string | null;
+  total: string | null;
+  commission: string | null;
 }
 
 export interface Vehicle {
@@ -302,10 +428,14 @@ export interface PolicyInput {
   policyTo?: string;
   coveragePeriodDays?: number;
   netPremium?: number;
+  surcharge?: number;
   policyFee?: number;
   brokerFee?: number;
   commission?: number;
+  tax?: number;
+  taxRate?: number;
   total?: number;
+  paymentFrequency?: PaymentFrequency;
   currency?: Currency;
   observations?: string;
   notes?: string;
@@ -323,6 +453,13 @@ export interface InstallmentInput {
   paidDate?: string;
   checkNumber?: string;
   isCash?: boolean;
+  netPremium?: number;
+  surcharge?: number;
+  policyFee?: number;
+  tax?: number;
+  taxRate?: number;
+  total?: number;
+  commission?: number;
 }
 export interface VehicleInput {
   make?: string;
@@ -373,6 +510,10 @@ export interface PolicyTypeRow {
   id: string;
   name: string;
   shortDescription: string | null;
+  /** IVA fraction for this line of business, 0.08 = 8%. Null means "not
+   *  configured" and the form falls back to DEFAULT_TAX_RATE — it does NOT
+   *  mean the line is untaxed. Serialized as a decimal string by Prisma. */
+  taxRate: string | null;
   _count?: { policies: number };
 }
 export interface AdjusterRow {
@@ -471,10 +612,14 @@ export interface PolicyDetail {
   policyTo: string | null;
   coveragePeriodDays: number | null;
   netPremium: string | null;
+  surcharge: string | null;
   policyFee: string | null;
   brokerFee: string | null;
   commission: string | null;
+  tax: string | null;
+  taxRate: string | null;
   total: string | null;
+  paymentFrequency: PaymentFrequency | null;
   currency: string | null;
   observations: string | null;
   notes: string | null;
@@ -898,6 +1043,8 @@ export interface BillingFacets {
 
 export interface StatementSummary {
   currency: LedgerCurrency;
+  /** Balance carried in from before the statement year — legacy's BALANCE FORWARD. */
+  opening: string;
   charges: string;
   credits: string;
   balance: string;
@@ -911,6 +1058,7 @@ export interface StatementSummary {
 export interface StatementDomainRow {
   domain: TransactionDomain;
   currency: LedgerCurrency;
+  opening: string;
   charges: string;
   credits: string;
   balance: string;
@@ -946,6 +1094,15 @@ export interface Statement {
     propertyCount: number;
     policyCount: number;
   };
+  /** Calendar year the statement covers; movements are scoped to it. */
+  year: number;
+  /**
+   * Periods this customer actually has, newest first. The current year is
+   * always present; each earlier year comes from an imported archive. Offering
+   * anything outside this list would render an empty statement that reads as
+   * "no activity" rather than "not imported".
+   */
+  availableYears: number[];
   summary: StatementSummary[];
   byDomain: StatementDomainRow[];
   byType: StatementTypeRow[];
@@ -981,6 +1138,8 @@ export interface CustomerDetail {
   properties: Property[];
   policies: Policy[];
   transactions: Transaction[];
+  /** Calendar year `transactions` covers. */
+  transactionYear: number;
   transactionSummary: TransactionSummaryRow[];
 }
 
@@ -1309,7 +1468,7 @@ export interface DiscardBatchResult {
   rejected: number;
 }
 
-/* ------------------------------------------ Policy OCR intake (GMX) */
+/* ------------------------------------- Policy OCR intake (GMX / ANA) */
 
 export type PolicyOcrBatchStatus =
   | "UPLOADED"
@@ -1351,6 +1510,27 @@ export interface PolicyOcrCoverage {
   insuredAmount: number | null;
   deductible: string | null;
   lossParticipation: string | null;
+  /** What the coverage COST, where the layout prints it separately from what
+   *  it pays out (ANA's add-on sections). GMX never prints one. */
+  premium?: number | null;
+}
+
+/** A row of ANA's `ITEM / YEAR / MAKE / BODY / SERIAL No. / PLATES` table. */
+export interface PolicyOcrVehicle {
+  item: string;
+  modelYear: string | null;
+  make: string | null;
+  bodyType: string | null;
+  vinNumber: string | null;
+  licensePlate: string | null;
+}
+
+export interface PolicyOcrDriver {
+  fullName: string;
+  licenseNumber: string | null;
+  address: string | null;
+  phone: string | null;
+  email: string | null;
 }
 
 export interface PolicyOcrMatchCandidate {
@@ -1360,6 +1540,18 @@ export interface PolicyOcrMatchCandidate {
   policyNumber: string;
 }
 
+/**
+ * A customer whose name resembles the printed insured name. A suggestion,
+ * not a match — the API never preselects one.
+ */
+export interface PolicyOcrCustomerSuggestion {
+  customerId: string;
+  customerName: string;
+  /** `EXACT` = same name tokens in any order; `PARTIAL` = one contains the other. */
+  tier: "EXACT" | "PARTIAL";
+  score: number;
+}
+
 export interface PolicyOcrDocument {
   id: string;
   pageNumber: number;
@@ -1379,9 +1571,18 @@ export interface PolicyOcrDocument {
   extractedNetPremium: string | null;
   extractedPolicyFee: string | null;
   extractedBrokerFee: string | null;
+  /** IVA off A.N.A.'s `TAX` cell. Null on GMX — its certificate carries no
+   *  premium, so no tax either. `LOCAL TAX` is not folded in; a non-zero one
+   *  shows up in `matchNote`. */
+  extractedTax: string | null;
   extractedTotal: string | null;
   extractedCoveragesJson: PolicyOcrCoverage[] | null;
   extractedPremiumPayment: string | null;
+  extractedCoveragePeriodDays: number | null;
+  extractedVehiclesJson: PolicyOcrVehicle[] | null;
+  extractedDriversJson: PolicyOcrDriver[] | null;
+  /** `PolicyType.name` the parser read, resolved to an id only at confirm. */
+  extractedPolicyTypeName: string | null;
   matchedPolicy: {
     id: string;
     policyNumber: string | null;
@@ -1390,6 +1591,7 @@ export interface PolicyOcrDocument {
   } | null;
   matchedCustomer: { id: string; name: string } | null;
   matchCandidates: PolicyOcrMatchCandidate[] | null;
+  customerSuggestions: PolicyOcrCustomerSuggestion[] | null;
   matchNote: string | null;
 }
 
@@ -1407,8 +1609,10 @@ export interface PolicyOcrReviewInput {
   netPremium?: number;
   policyFee?: number;
   brokerFee?: number;
+  tax?: number;
   total?: number;
   premiumPayment?: string;
+  coveragePeriodDays?: number;
   coveragesJson?: PolicyOcrCoverage[];
   matchedPolicyId?: string;
   matchedCustomerId?: string;
@@ -1432,9 +1636,14 @@ export interface PolicyOcrConfirmDocument {
   netPremium?: number;
   policyFee?: number;
   brokerFee?: number;
+  tax?: number;
   total?: number;
   premiumPayment?: string;
+  coveragePeriodDays?: number;
   coveragesJson?: PolicyOcrCoverage[];
+  /** Explicit lookup picks; both beat the name the parser read. */
+  policyTypeId?: string;
+  insuranceProviderId?: string;
   postPremium?: boolean;
 }
 

deploy/galactus/jorgecuadros-app.compose.yml

@@ -61,6 +61,11 @@ services:
       INGEST_DIR: /data/ingest
       BACKUP_DIR: /data/backups
       MIGRATION_ENV: prod
+      # The API applies pending Prisma migrations at container start, before
+      # Nest listens, and refuses to start if they fail (docker/api-entrypoint.sh).
+      # Set false ONLY when the schema is being moved by hand — the app will
+      # then boot against whatever schema it finds.
+      RUN_MIGRATIONS: ${RUN_MIGRATIONS:-true}
       # Credentials the "Operaciones" screen runs mysqldump/mysql as. NOT the
       # application user: --single-transaction needs the global RELOAD privilege
       # and the app user has only ALL ON jorgecuadros.*, so every backup, sync
@@ -69,6 +74,14 @@ services:
       # apps/api/src/ops/ops.service.ts.
       OPS_DB_ADMIN_USER: ${OPS_DB_ADMIN_USER:-root}
       OPS_DB_ADMIN_PASSWORD: ${OPS_DB_ADMIN_PASSWORD:?OPS_DB_ADMIN_PASSWORD must be set}
+      # Read-only replica that my.jorgecuadros.com serves customers from. Used
+      # ONLY to report health on the Operaciones screen — the account holds
+      # REPLICATION CLIENT and nothing else, so it cannot read a single row.
+      # Unset is a supported state: the panel then says "no configurada"
+      # instead of erroring, which is correct before cutover and in dev.
+      REPLICA_DB_HOST: ${REPLICA_DB_HOST:-}
+      REPLICA_DB_USER: ${REPLICA_DB_USER:-}
+      REPLICA_DB_PASS: ${REPLICA_DB_PASS:-}
       S3_ENDPOINT: ${S3_ENDPOINT:?S3_ENDPOINT must be set}
       S3_BUCKET: ${S3_BUCKET:-jorgecuadros-documents}
       MINIO_ROOT_USER: ${MINIO_ROOT_USER:?MINIO_ROOT_USER must be set}
@@ -124,8 +137,12 @@ services:
     dns_search:
       - ${TAILNET_SUFFIX:-tail01aa2.ts.net}
     environment:
-      # Public API URL the browser calls (injected at runtime, see layout.tsx).
+      # OPTIONAL override of the API URL the browser calls (injected at runtime,
-      API_ORIGIN: ${API_ORIGIN:?API_ORIGIN must be set}
+      # see layout.tsx). Leave it unset: the browser then derives the origin
+      # from the page it loaded — same host on port 3001 over plain HTTP, or
+      # /api behind a TLS-terminating proxy. Set it only when the API really
+      # lives on a different host than the web app.
+      API_ORIGIN: ${API_ORIGIN:-}
     ports:
       - "${WEB_PORT:-3000}:3000"
     depends_on:

deploy/jorgecuadros-app.env.example

@@ -8,10 +8,21 @@
 APP_TAG=latest
 
 # --- Public URLs (what the end user's BROWSER hits) ---------------------------
-# API_ORIGIN is injected into the web app at runtime and used for browser fetches
+# API_ORIGIN is OPTIONAL and normally left unset. The browser derives the API
-# + document download links, so it must be browser-reachable (not swarm-internal).
+# origin from the page it loaded (apps/web/src/lib/api.ts): same host on port
-# WEB_ORIGIN is the web app's own public origin; the API allows it via CORS.
+# 3001 over plain HTTP, or the same-origin /api path when the page is served
-API_ORIGIN=http://192.168.4.212:3001
+# over https by a TLS-terminating proxy that maps /api to the API. That is what
+# lets the same deployment move — tailnet, office LAN, demo domain — untouched.
+# Set it only when the API genuinely lives on a different host than the web app;
+# it is used for browser fetches AND document download links, so it must be
+# browser-reachable (never a swarm-internal name).
+#API_ORIGIN=http://192.168.4.212:3001
+#
+# WEB_ORIGIN is the list of public origins the web app is reached under; the API
+# allows them via CORS. COMMA-SEPARATED — one deployment is reachable under
+# several origins (LAN IP, tailnet name, demo domain) and a credentialed fetch
+# from an origin missing here gets no CORS headers and fails. A same-origin
+# setup (web + API behind one proxy) never hits CORS at all.
 WEB_ORIGIN=http://192.168.4.212:3000
 
 # Published ports on the swarm host.

deploy/jorgecuadros-app.stack.yml

@@ -41,6 +41,11 @@ services:
       INGEST_DIR: /data/ingest
       BACKUP_DIR: /data/backups
       MIGRATION_ENV: prod
+      # The API applies pending Prisma migrations at container start, before
+      # Nest listens, and refuses to start if they fail (docker/api-entrypoint.sh).
+      # Set false ONLY when the schema is being moved by hand — the app will
+      # then boot against whatever schema it finds.
+      RUN_MIGRATIONS: ${RUN_MIGRATIONS:-true}
       # Credentials the "Operaciones" screen runs mysqldump/mysql as. NOT the
       # application user: --single-transaction needs the global RELOAD privilege
       # and the app user has only ALL ON jorgecuadros.*, so every backup, sync
@@ -92,8 +97,12 @@ services:
     labels:
       io.jorgecuadros.role: "web"
     environment:
-      # Public API URL the browser calls (injected at runtime, see layout.tsx).
+      # OPTIONAL override of the API URL the browser calls (injected at runtime,
-      API_ORIGIN: ${API_ORIGIN:?API_ORIGIN must be set}
+      # see layout.tsx). Leave it unset: the browser then derives the origin
+      # from the page it loaded — same host on port 3001 over plain HTTP, or
+      # /api behind a TLS-terminating proxy. Set it only when the API really
+      # lives on a different host than the web app.
+      API_ORIGIN: ${API_ORIGIN:-}
     ports:
       - target: 3000
         published: ${WEB_PORT:-3000}

deploy/scripts/check-replication.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+#
+# Is the my.jorgecuadros.com read replica actually replicating?
+#
+#   deploy/scripts/check-replication.sh
+#
+# Answers it from the REPLICA alone, so it needs no credentials for the
+# galactus master — only ssh to the VPS. Exits non-zero when replication is
+# broken or lagging, so it is usable from cron or a monitor.
+#
+# Why not just eyeball `SHOW REPLICA STATUS`: the two obvious fields are both
+# misleading on their own.
+#
+#   * "Replica_IO_Running: Yes" only means the network thread is alive. The SQL
+#     thread can be stopped with a duplicate-key error while IO keeps happily
+#     downloading binlog, so the replica looks busy and falls further behind.
+#
+#   * "Seconds_Behind_Source: 0" reads 0 both when there is genuinely nothing
+#     to apply AND when the IO thread is disconnected — there is no event to
+#     measure staleness against, so absence of work is reported as being current.
+#
+# The trustworthy check is GTID_SUBTRACT(Retrieved, Executed): binlog we have
+# fetched but not yet applied. Empty means genuinely caught up.
+
+set -uo pipefail
+
+REPLICA_HOST="${REPLICA_HOST:-opc@163.192.62.37}"
+MAX_LAG="${MAX_LAG:-30}"
+
+raw=$(ssh -o ConnectTimeout=10 -o BatchMode=yes "$REPLICA_HOST" \
+  'sudo mysql -e "SHOW REPLICA STATUS\G"' 2>/dev/null)
+
+if [ -z "$raw" ]; then
+  echo "FAIL: could not reach $REPLICA_HOST or mysql returned nothing"
+  exit 2
+fi
+
+# sed rather than `head -n1`: on some machines `head` is shadowed by LWP's
+# HTTP head(1), which silently mangles the pipeline instead of erroring.
+field() { printf '%s\n' "$raw" | grep -E "^[[:space:]]*$1:" | sed -n '1p' | sed -E "s/^[[:space:]]*$1:[[:space:]]*//"; }
+
+io=$(field Replica_IO_Running)
+sql=$(field Replica_SQL_Running)
+lag=$(field Seconds_Behind_Source)
+io_err=$(field Last_IO_Error)
+sql_err=$(field Last_SQL_Error)
+
+# The authoritative "am I caught up" test: anything fetched but not applied.
+backlog=$(ssh -o ConnectTimeout=10 -o BatchMode=yes "$REPLICA_HOST" \
+  'sudo mysql -NB -e "
+     SELECT IFNULL(NULLIF(GTID_SUBTRACT(
+       (SELECT RECEIVED_TRANSACTION_SET FROM performance_schema.replication_connection_status),
+       @@GLOBAL.gtid_executed), \"\"), \"(none)\")" 2>/dev/null' 2>/dev/null)
+[ -z "$backlog" ] && backlog="(performance_schema off — using lag only)"
+
+echo "replica     : $REPLICA_HOST"
+echo "IO thread   : $io"
+echo "SQL thread  : $sql"
+if [ "$lag" = "NULL" ] || [ -z "$lag" ]; then
+  echo "lag         : NULL"
+else
+  echo "lag         : ${lag}s"
+fi
+echo "unapplied   : $backlog"
+[ -n "$io_err" ]  && echo "IO error    : $io_err"
+[ -n "$sql_err" ] && echo "SQL error   : $sql_err"
+
+rc=0
+[ "$io" = "Yes" ]  || { echo "FAIL: IO thread not running"; rc=1; }
+[ "$sql" = "Yes" ] || { echo "FAIL: SQL thread not running"; rc=1; }
+[ -n "$io_err" ]   && { rc=1; }
+[ -n "$sql_err" ]  && { rc=1; }
+# SHOW reports NULL lag whenever EITHER thread is down — there is no applied
+# event to measure against. Never report which one from the lag alone; the
+# thread fields above already said, and guessing produces a wrong diagnosis.
+if [ "$lag" = "NULL" ] || [ -z "$lag" ]; then
+  echo "FAIL: lag is NULL (replication not applying)"
+  rc=1
+elif [ "$lag" -gt "$MAX_LAG" ] 2>/dev/null; then
+  echo "WARN: lag ${lag}s exceeds ${MAX_LAG}s"
+  rc=1
+fi
+
+[ $rc -eq 0 ] && echo "OK: replica is running and caught up"
+exit $rc

docker/api-entrypoint.sh

@@ -0,0 +1,102 @@
+#!/bin/sh
+# Apply pending Prisma migrations, then hand off to the API.
+#
+# WHY THE CONTAINER AND NOT THE DEPLOY WORKFLOW
+#
+# The workflow still has its own `prisma migrate deploy` step and that is not
+# redundant: it runs BEFORE the new images are pulled, i.e. while the OLD code
+# is still serving, which is the order expand/contract migrations are designed
+# around (see docs/DEPLOY_AND_MIGRATIONS.md). Doing it here as well closes the
+# gaps that step cannot:
+#
+#   - The runner has to reach MySQL directly. When it cannot, the deploy is run
+#     with `skip_migrate=true` and the schema silently does not move — the app
+#     then boots against a schema that is one release behind, which surfaces
+#     later as a column-not-found at runtime rather than as a failed deploy.
+#   - A container restarted by `restart: unless-stopped` after a host reboot,
+#     or a stack re-applied by hand in Portainer, never goes through the
+#     workflow at all.
+#
+# `migrate deploy` is idempotent, so running it in both places costs one
+# no-op query on the normal path.
+#
+# THE API DOES NOT START IF THE MIGRATION FAILS. That is deliberate: serving
+# against a schema that does not match the code is worse than being down,
+# because the failures it produces are partial and silent (a write to a column
+# that does not exist yet fails for one feature while the rest of the app looks
+# healthy). The container exits non-zero and Docker's restart policy retries.
+set -e
+
+SCHEMA=/repo/packages/database/prisma/schema.prisma
+
+log() { echo "[entrypoint] $*"; }
+
+if [ "${RUN_MIGRATIONS:-true}" != "true" ]; then
+  log "RUN_MIGRATIONS=${RUN_MIGRATIONS} — skipping migrations, starting the API"
+  exec "$@"
+fi
+
+if [ -z "${DATABASE_URL}" ]; then
+  log "DATABASE_URL is unset; cannot migrate." >&2
+  log "Set it, or set RUN_MIGRATIONS=false if you migrate out of band." >&2
+  exit 1
+fi
+
+# pnpm's hoisted linker normally puts the CLI in the root .bin, but the
+# workspace package keeps its own link too. Accept either rather than pinning
+# a layout detail of the installer — the Dockerfile asserts at build time that
+# one of these exists, so a missing CLI breaks the image build, not a deploy.
+PRISMA=""
+for candidate in /repo/node_modules/.bin/prisma \
+                 /repo/packages/database/node_modules/.bin/prisma; do
+  if [ -x "$candidate" ]; then
+    PRISMA="$candidate"
+    break
+  fi
+done
+if [ -z "$PRISMA" ]; then
+  log "prisma CLI not found in this image; cannot migrate." >&2
+  exit 1
+fi
+
+# Retry ONLY a connection failure (P1001). On a full bring-up the database
+# container can still be starting, and on galactus the API additionally has to
+# resolve the host's MagicDNS name — a lookup that is unreliable for the first
+# moments after a host reboot (see the dns block in the app compose file, and
+# docs/DEPLOY_AND_MIGRATIONS.md).
+#
+# Every other failure exits immediately. Retrying a migration that is actually
+# broken just delays the same error behind a minute of noise, and P3005 in
+# particular needs a human.
+attempt=1
+max="${MIGRATE_MAX_ATTEMPTS:-20}"
+delay="${MIGRATE_RETRY_SECONDS:-3}"
+
+while : ; do
+  log "prisma migrate deploy (attempt ${attempt}/${max})"
+  if output=$("$PRISMA" migrate deploy --schema "$SCHEMA" 2>&1); then
+    printf '%s\n' "$output"
+    log "migrations up to date"
+    break
+  fi
+  printf '%s\n' "$output" >&2
+
+  if ! printf '%s' "$output" | grep -q 'P1001'; then
+    log "migrate deploy FAILED — refusing to start the API." >&2
+    if printf '%s' "$output" | grep -q 'P3005'; then
+      log "P3005: the database has tables but no migration history. This is a" >&2
+      log "database that predates Prisma migrations. Baseline it ONCE with:" >&2
+      log "  npx prisma@5 migrate resolve --applied 0000_init --schema $SCHEMA" >&2
+    fi
+    exit 1
+  fi
+
+  if [ "$attempt" -ge "$max" ]; then
+    log "database unreachable after ${max} attempts — giving up." >&2
+    exit 1
+  fi
+  attempt=$((attempt + 1))
+  sleep "$delay"
+done
+
+exec "$@"

docker/api.Dockerfile

@@ -113,5 +113,21 @@ ENV APP_VERSION=$APP_VERSION \
     GIT_SHA=$GIT_SHA \
     BUILD_DATE=$BUILD_DATE
 
+# Pending migrations are applied at container start, before Nest listens —
+# see the header of the script for why this is done here as well as in the
+# deploy workflow. Asserted at BUILD time so a missing prisma CLI breaks the
+# image build rather than a production boot: the runtime layer copies
+# /repo/node_modules wholesale, and which of these two paths carries the bin
+# is an implementation detail of pnpm's hoisted linker.
+COPY docker/api-entrypoint.sh /usr/local/bin/api-entrypoint.sh
+RUN chmod +x /usr/local/bin/api-entrypoint.sh
+RUN for c in /repo/node_modules/.bin/prisma \
+             /repo/packages/database/node_modules/.bin/prisma; do \
+      if [ -x "$c" ]; then echo "prisma CLI found at $c"; exit 0; fi; \
+    done; \
+    echo "FATAL: prisma CLI is not in the runtime layer; api-entrypoint.sh cannot migrate" >&2; \
+    exit 1
+
 EXPOSE 3001
+ENTRYPOINT ["/usr/local/bin/api-entrypoint.sh"]
 CMD ["node", "apps/api/dist/main.js"]

docs/BACKLOG.md

@@ -12,8 +12,8 @@ carries the reasoning. Close an item *there* as well as here, or the two drift.
 **Verified against dev at compile time** (re-run before trusting the numbers):
 
 ```
-policy_types: AUTO, LICENCIAS, MULT
+policy_types: AUTO, LICENCIAS, MULT      (+ M_EMPR after 20260815160000)
-policies NULL policyTypeId: 5
+policies NULL policyTypeId: 5            (0 after 20260815160000)
 policies pending liquidación: 226
 customers: 1536
 last tag: v1.0.6 (2026-08-02 02:06 UTC) — 14 commits, 5 migrations behind HEAD
@@ -83,7 +83,7 @@ guess.
 | 1.3 | Carrier API **direction**: outbound quote/issue (ANA supports today) or inbound portfolio sync (no evidence either carrier offers it) | whether §4 is buildable at all | INSURANCE §4 |
 | 1.4 | CFE amount: the rounded barcode figure (`$268`, what is paid at the window) or the exact breakdown total (`$268.88`) | the parser currently takes the barcode | STATEMENT_OCR / RECEIPT §2 |
 | 1.5 | The Seguros USD bank's name, currency and details | multi-bank is built; that account does not exist yet | RECEIPT §3 |
-| 1.6 | Recycling triggers — exact "1 year inactive" / "cancelled" definitions, and whether recycling ever means true data purge | §4 recycling | RECEIPT §4 |
+| 1.6 | Whether recycling ever means a true data purge. The *triggers* are now settled and built (see §5 "NUMid allocation"); what is still open is whether a recycled id's old rows are ever deleted rather than left attached to the previous customer | nothing — the allocator ships without a purge | RECEIPT §4 |
 | 1.7 | Notice body in Spanish or English | `Customer` carries no language preference | INSURANCE §1 |
 | 1.8 | How to model `TRASPASOS PAYPAL` — a clearing account, not a customer, carrying −7.03M MXN over 309 movements and therefore topping the adeudo worklist | deliberately not special-cased in code | RESUME §6 |
 | 1.9 | The 78 policyholders with no email — skip silently or produce a print worklist | recommendation is the worklist | INSURANCE §1 |
@@ -98,16 +98,31 @@ in the same phone call — (55) 5480-4000.
 
 ## 2. Live data defects — open, and confirmed open today
 
-### 2.1 `policy_types` is missing `INCENDIO` and `M_EMPR`, and 5 policies are orphaned
+### 2.1 ~~`policy_types` missing rows + 5 orphaned policies~~ — FIXED 2026-08-15
 
 `policyTypeId` is `String?` with a plain relation, so Prisma's default is
-`SetNull`. The spec's recommended `onDelete: Restrict` was **never applied**.
+`SetNull`, and `removePolicyType()` had no in-use guard — deleting a lookup row
-Five `m_empr` policies lost their ramo; four of them are pending liquidación
+returned 200 and silently blanked the ramo on every policy using it. That is
-and are invisible to every ramo-filtered query — including the pending report
+what happened to `M_EMPR` and its 5 `m_empr` policies.
-§2 is supposed to produce.
 
-Fix alongside the liquidación work (3.1), since it distorts that feature's own
+Closed by `20260815160000_policy_type_repair` plus the guard in
-report. Source: INSURANCE "Two defects found while verifying this spec".
+`policies.service.ts`:
+
+- `M_EMPR` restored and the 5 policies re-pointed at it, scoped to
+  `policyTypeId IS NULL AND legacySourceTable = 'm_empr'` so it cannot claim a
+  policy blanked for some other reason. Idempotent; verified against dev inside
+  a rolled-back transaction.
+- **`INCENDIO` deliberately not recreated.** The legacy `INCENDIO` table has
+  1 row and it never loaded, so the type has zero policies — restoring it would
+  only add a dead option to the type picker.
+- Deleting an in-use policy type, carrier or adjuster now **refuses** with the
+  name and the count. `claims.adjusterId` had the identical `SET NULL` trap and
+  is guarded too. `onDelete: Restrict` at the schema level was not applied —
+  the application guard gives a Spanish message the operator can act on, where
+  a raw FK error would not.
+- The duplicate `ANA` carrier row (1 policy) was merged into `ANA SEGUROS`
+  (738), since OCR now assigns the carrier automatically and two rows would
+  keep splitting the book.
 
 ### 2.2 ≤41 MULT second settlements were dropped in migration
 
@@ -164,13 +179,41 @@ Each of these is a known, deliberate stopping point rather than a bug.
   be added.
 - No `SKIPPED_NO_EMAIL` worklist (see 1.9).
 
+**Captura de pólizas — desglose de primas** (built 2026-08-18)
+- **IVA y prima total no existen en los datos legacy.** En Access eran
+  controles calculados sin campo, así que las 2,378 pólizas migradas leen
+  `tax` y `total` en null hasta que alguien las edite. No es recuperable: no
+  hay de dónde.
+- **`LOCAL TAX` de A.N.A. no se captura.** El IVA (`TAX`) sí — se guarda desde
+  2026-08-18 — pero `LOCAL TAX` es un gravamen distinto sin columna destino y
+  **no** se suma al IVA: sumarlo daría una cifra que ya no divide de vuelta a
+  una tasa. Imprime 0.00 en todas las pólizas vistas hasta hoy; una distinta
+  de cero levanta la nota *"impuesto local N no capturado"* y significa que
+  `total` no cuadra contra `netPremium + policyFee + tax`.
+- **`Policy.taxRate` queda en null por la ruta OCR.** A.N.A. imprime el monto
+  del IVA, no la tasa, y despejarla a la inversa inventaría una tasa que el
+  documento nunca declaró. El formulario resuelve una desde el ramo.
+- **El recargo no se valida contra la forma de pago en datos migrados.** El
+  formulario lo deshabilita en ANUAL/CONTADO, pero
+  `backfill_policy_premium_breakdown.py` solo advierte cuando encuentra una
+  póliza anual con recargo; no la corrige.
+- **Las parcialidades 3 y 4 no llevan desglose.** Access solo dibujó la fila
+  de dinero dos veces, así que una póliza trimestral capturada hoy sí puede
+  llenar las cuatro a mano, pero no hay nada legacy que migrar a las dos
+  últimas.
+
 **Policy OCR** — [`POLICY_OCR.md`](POLICY_OCR.md)
-- **GMX only.** The dispatcher is a `[provider, pattern]` table plus a parser
+- **GMX and A.N.A. only.** The dispatcher is a `[provider, pattern]` table plus
-  map, so a second carrier is one function and two entries — but no other
+  a parser map, so a third carrier is one function and two entries — but no
-  layout has been seen, and guessing produces a parser nobody can verify.
+  other layout has been seen, and guessing produces a parser nobody can verify.
 - **The `recibo` PDF is unread.** The GMX certificate carries no premium at
   all; reading the separate receipt and pairing it to its certificate is what
-  would let `postPremium` stop being a manual tick.
+  would let `postPremium` stop being a manual tick. A.N.A. prints its premium
+  on the face, so this is a GMX-only gap.
+- **No `insuranceProviderId` beyond the two OCR carriers.** Confirm resolves
+  the parser's provider to an `insurance_providers` row by name, so GMX and
+  A.N.A. land correctly; a policy typed in by hand still gets whatever the
+  operator picks.
 - **No versioning.** A re-issued policy arrives as a new certificate with the
   same number and confirm updates the existing row. Nothing records that this
   is the 2027 issue of that policy.
@@ -184,6 +227,33 @@ Each of these is a known, deliberate stopping point rather than a bug.
 - Handwritten folder numbers are deliberately not an input to matching
   (Tesseract read `405` as `205`).
 
+**NUMid allocation** — `POST /customers/:id/portal-access` assigns the portal
+"Security Number", on a staff action rather than at create time, because an
+insurance-only customer has no reason to hold a utilities id.
+
+- **Recycling is built but switched off.** `numid.recycleEmpty` in `app_settings`
+  defaults to false, and that default is a safety property, not a preference:
+  every reusable id still exists in Access DATGRAL, and a `--sync` migration run
+  upserts refs with `ON DUPLICATE KEY UPDATE customerId`
+  (`transform_customers.py:327`), so an id recycled today is handed back to its
+  Access owner on the next sync and the customer given it loses portal access.
+  **Flip it on after utilities cuts over**, or for ids deleted at the source.
+- **A full re-import would destroy every natively allocated id — now guarded.**
+  `transform_customers.py:246` truncates `customers` and `customer_legacy_refs`
+  (and the other transforms truncate everything they own), then rebuild from
+  Access alone. `migration/native_guard.py` runs before any of it and refuses
+  when the target holds rows Access has never seen; `run_all.py --force-full`,
+  or the checkbox in the REIMPORT confirm, overrides and deletes them. **`--sync`
+  remains the correct path for any database with native rows** — the guard stops
+  the loss, it does not make full mode preserve anything.
+- **The empty-id rule exists twice**: enforced in `numid.service.ts`
+  (`EMPTY_NUMID_SQL`) and reported by `scripts/numid-audit.sql`. They agree today
+  (both return 1089, 1094, 1134, 1143 on dev); they are not mechanically kept in
+  step, so change them together.
+- **No un-assign.** Nothing removes a NUMid once given, and nothing reports which
+  ids were recycled from whom beyond the `customer.portal-access` activity-log
+  entry.
+
 **Bank** — the concept→ramo classifier is **won't-build**, not pending.
 `concepto` is a payee name (0 of 22,354 match a category) and TABLA RAMODOS is
 a property-management expense chart, not the business-line split it was assumed

docs/DEPLOY_AND_MIGRATIONS.md

@@ -56,9 +56,11 @@ workflow's last step fails if the API does not report the tag you dispatched.
    `pre-migrate-<tag>-<timestamp>.sql.gz`, which is exactly what the
    **Operaciones** admin screen lists and can restore. A dump taken on the CI
    runner would be unreachable by the only restore path the platform has.
-3. **`prisma migrate deploy`** — as a workflow *step*, never the container
+3. **`prisma migrate deploy`** — as a workflow *step*, so the schema moves
-   `CMD`. If it were the CMD, N replicas would race each other applying the
+   while the OLD code is still serving, which is the order expand/contract is
-   same migration.
+   designed around. **The api container repeats this at start** (below); the
+   command is idempotent, so on the normal path the container's run is a
+   no-op.
 4. **app** — the new api + web images.
 5. **Verify** — `GET /version` on the running API must report the dispatched
    tag.
@@ -141,6 +143,59 @@ Commit the generated `migrations/<timestamp>_add_foo/` directory. `db push` is
 now a local-scratch tool only — using it against a database with history
 desynchronises it from `_prisma_migrations`.
 
+If you hand-write a migration instead of generating one, check it against what
+Prisma would have produced before committing — a hand-written file that drifts
+from `schema.prisma` fails on the *next* deploy, not this one:
+
+```bash
+prisma migrate diff \
+  --from-schema-datamodel <schema.prisma at the previous commit> \
+  --to-schema-datamodel packages/database/prisma/schema.prisma --script
+```
+
+## Migrations also run at container start
+
+`docker/api-entrypoint.sh` is the api image's `ENTRYPOINT`. It runs
+`prisma migrate deploy` and only then `exec`s the API. **If the migration
+fails the container exits non-zero and the API never listens.**
+
+That is the point. Serving against a schema that does not match the code is
+worse than being down, because the failures are partial and silent — a write
+to a column that does not exist yet breaks one feature while the rest of the
+app looks healthy.
+
+This does not replace the workflow step, which still runs first and against
+the old code. It covers what that step cannot:
+
+- **`skip_migrate: true`.** Previously that left the schema behind with no
+  further safety net, and the mismatch surfaced later as a runtime error. Now
+  it just moves the migration into the container, so it is a safe choice when
+  the runner cannot reach MySQL.
+- **Restarts that never touch the workflow** — `restart: unless-stopped`
+  bringing the stack back after a host reboot, or a stack re-applied by hand
+  in Portainer.
+
+Behaviour worth knowing:
+
+| | |
+|---|---|
+| `RUN_MIGRATIONS=false` | Skip and start anyway. Plumbed through both app stack files. For when the schema is being moved by hand. |
+| `DATABASE_URL` unset | Refuses to start (it would have failed at Nest boot anyway, but this says why). |
+| Cannot reach the database (**P1001**) | Retries, default 20 × 3s. Covers a cold `db` container and galactus's MagicDNS lookup right after a reboot. `MIGRATE_MAX_ATTEMPTS` / `MIGRATE_RETRY_SECONDS` tune it. |
+| Any other failure | Exits at once. Retrying a broken migration only delays the same error; **P3005** additionally prints the `migrate resolve --applied 0000_init` hint. |
+
+**On replicas.** Both stacks are `replicas: 1` and must stay that way for an
+unrelated reason (the servicios email sweep has no DB lock — see the caveats
+below). If that ever changes, concurrent `migrate deploy` runs are safe on
+their own: Prisma takes a database advisory lock, so the others block and then
+find nothing pending. They would each pay the wait at startup, not corrupt
+anything.
+
+The prisma CLI has to be present in the runtime layer for any of this. The
+image copies `/repo/node_modules` wholesale so it already is, and the
+Dockerfile **asserts it at build time** — a missing CLI breaks the image
+build rather than a production boot.
+
 ## galactus vs cubex
 
 `galactus` is standalone Docker (Portainer endpoint **3**), `cubex` is a 3-node
@@ -319,9 +374,10 @@ backup does them (see `deploy/scripts/pre-migrate-backup.mjs`):
   Portainer serves a self-signed certificate. It is scoped to that one step,
   which talks to nothing but Portainer. Replacing the certificate and dropping
   the flag is the real fix.
-- The runner lives on cubex and must reach the target host's Portainer (9443)
+- The runner lives on cubex and must reach the target host's Portainer (9443).
-  **and** MySQL (3306). If it cannot reach 3306, run the migration by hand from
+  It should also reach MySQL (3306) for the migrate step, but that is no longer
-  a host that can and dispatch with `skip_migrate: true`.
+  load-bearing — dispatch with `skip_migrate: true` and the api container
+  applies the migrations itself at start.
 - `bootstrap: true` lets the pre-migrate backup be skipped when no API container
   exists yet. Use it for a first-ever deploy only — it is the one switch that
   lets a migration run with no restore point.

docs/INSURANCE_FEATURES_SPEC.md

@@ -440,6 +440,12 @@ take a `policyType` select param. The workflow is *not* MULT-only: the legacy
 
 Params: ramo (with an "todos" option), aseguradora, date range on `policyFrom`.
 Columns: póliza, cliente, ramo, aseguradora, vigencia, prima neta, forma de pago.
+
+ℹ️ `forma de pago` became a real column on 2026-08-18 (`Policy.paymentFrequency`).
+It is **null on every policy migrated before that date** — the original ETL
+marked Access's `FORMA PAGO` consumed and then never wrote it anywhere — so the
+report must render null as "—" rather than assuming annual. Running
+`backfill_policy_premium_breakdown.py` recovers it from the staged Parquet.
 Totals: count + prima neta sum per currency (**never collapse MXN and USD** —
 same constraint as the billing module).
 

docs/POLICY_OCR.md

@@ -34,7 +34,7 @@ was **reused, not copied**.
 |---|---|
 | API module | `apps/api/src/policy-ocr/` (service, controller, DTOs, matcher, parser) |
 | Shared OCR seam | `apps/api/src/ocr/ocr.module.ts` |
-| Tables | `policy_ocr_batches`, `policy_ocr_documents` (`20260801000000_policy_ocr_intake`) |
+| Tables | `policy_ocr_batches`, `policy_ocr_documents` (`20260801000000_policy_ocr_intake`, extended by `20260815120000_policy_ocr_ana` and `20260815160000_policy_type_repair`) |
 | Web | `components/PolicyCaptura.tsx` (tab shell), `PolicyOcrIntake.tsx` (upload), `PolicyOcrReview.tsx` (review queue) |
 | Abilities | `policy:ingest`, `policy:ocr-review` — both **STAFF** |
 
@@ -84,8 +84,9 @@ feature's core assumption.
 Utility statements arrive **bundled, one customer per page** — so there, one
 page is one document and the parser runs per page. A policy PDF is the
 opposite: the GMX certificate is a 2-page document where page 1 carries the
-contract header and page 2 carries the per-coverage table, and **both pages
+contract header and page 2 carries the per-coverage table (and the PVL
-describe the same policy**. So the pipeline concatenates every page's text
+especificación runs to ten), and **every page describes the same policy**. So
+the pipeline concatenates every page's text
 (`\n\n` between pages, which also keeps `ocrRawText` readable for debugging)
 and runs the parser and the matcher exactly **once per file**.
 
@@ -133,6 +134,203 @@ customers do occur (one group policy bound by two related parties), and
 picking arbitrarily would silently book the wrong coverage against the wrong
 person.
 
+### Name suggestions on the zero-hit path
+
+When the policy number finds nothing — the new-policy case, where a human has
+to pick a customer anyway — `name-matcher.ts` ranks the customer book against
+the printed insured name and the review screen offers the top three as
+one-click buttons above the picker. They are written to
+`policy_ocr_documents.customerSuggestions`, deliberately **not** to
+`matchCandidates`, so a name hint can never be read as a policy-number hit.
+Nothing sets `matchedCustomerId`; the rule above is unchanged.
+
+The problem is only ordering: the office books customers surname-first
+(`WAGONER, PAMELA`) and carriers print them given-name-first
+(`PAMELA DENISE WAGONER`), so a string compare never hits while a **token-set**
+compare does. Names are normalized (accents folded, so OCR's `MUNOZ` reaches
+the book's `MUÑOZ`; initials, `DE`/`LA`/`Y`, `JR`, `S.A. DE C.V.` and any token
+containing a digit dropped — ANA prints the phone hard against the name as
+`Ph.3102001538`). Two tiers:
+
+| Tier | Rule |
+|---|---|
+| `EXACT` | identical token sets, any order |
+| `PARTIAL` | one set contains the other, ≥2 shared tokens, **and** the surname is present |
+
+Both thresholds come from measuring the real book (1536 customers):
+
+- 1487 distinct token sets, so `EXACT` cross-person collisions are ~0
+- loosen to surname + first given name and 131 customers (8.5%) collide —
+  the book holds `MCWILLIAMS, BRIAN MICHAEL` *and* `MCWILLIAMS, BRIAN`
+- 185 surnames are shared by 524 customers, so one token is never evidence;
+  hence the ≥2 floor and the explicit surname requirement, which is what stops
+  `JERRY MARILYN` reaching `ESTRADA, JERRY & MARILYN` on given names alone
+
+Replaying every book row as a carrier would print it (given-name-first, joint
+spouse dropped): 97.9% top-ranked correct, 0.9% no suggestion, 1.2% a
+different row — and all but two of those are the same human on a duplicate or
+variant row (`MOLNAR, JANOS` vs `MOLNAR,  JANOS`, `IBARRA, ISMAEL &`). The
+two genuine wrong-person cases are `CUADROS, JORGE JR` against three
+`CUADROS, JORGE H.`, and they appear as a tie in the list rather than as a
+single answer.
+
+A blob is refused outright (>8 tokens or >80 characters): GMX's especificación
+has no field labels and the parser has been seen handing its whole first page
+over as `insuredName`, which would find a surname somewhere in the prose.
+`(SIN NOMBRE)` — 14 rows the migration left — is skipped on both sides.
+
+**Not used for utility statements.** There the registrant genuinely is not the
+customer (the `CATT, RANDY` finding above), so the same trick would be wrong,
+not merely noisy.
+
+## GMX ships two unrelated documents for the same policy
+
+The office downloads both from the same portal, and either can land in a
+batch. They share only the brand and the policy number, so `parseGmx` is a
+two-line dispatcher over two real parsers — both returning `provider: "GMX"`,
+because the matcher keys on the policy number alone and must not care which
+artifact was uploaded.
+
+| | **Caratula** (`…_Traduccion.pdf`) | **Especificación** (`…-CondicionesParticulares.pdf`) |
+|---|---|---|
+| Language | English (free translation) | Spanish |
+| Shape | boxed header table + 4-column coverage table | 10 pages of prose, no tables at all |
+| Header fields | Policy / Insured / Broker / Term / From / To / Currency | insured name, risk location, property description |
+| Dates, broker, currency field | yes | **none printed** |
+| Coverages | one row per risk | section heading + `Límite Máximo de Responsabilidad:` |
+| Parser | `parseGmxCaratula` | `parseGmxEspecificacion` |
+
+Selected by `isEspecificacion` on the PVL page header
+(`ESPECIFICACIÓN QUE SE ADHIERE`, `PVL Hogar`, `Nombre del asegurado`).
+
+Three things about the especificación are worth knowing before touching it:
+
+- **The policy number's group widths differ between the two.** The caratula
+  reads `007-037-07005947-0000-02` and the especificación
+  `07-037-07006957-00000-01` — 2 digits in the first group, 5 in the fourth.
+  The original parser pinned the widths, so it read one family and returned
+  null on the other. `POLICY_NUMBER_SHAPE` now matches the shape, and since
+  the especificación prints the number on all ten page headers, the ten
+  readings cross-check each other (disagreement is noted, not resolved — the
+  same rule the zona federal parser applies to its clave).
+- **Coverages are found by anchoring on the limit label and walking backwards
+  for the heading.** There is no row shape to match. A heading is a short line
+  *preceded by a blank line* — that last condition is the whole trick, since
+  length alone cannot tell a heading from the wrapped tail of the paragraph
+  above it (`efectuados.`, `Y CADA PÉRDIDA.`), and without it coverages get
+  named after the last word of the preceding prose.
+- **Vigencia, agente and prima are absent by design**, not unread. The parser
+  says so in a note, so a reviewer seeing three empty fields does not read it
+  as a broken parse.
+
+  **These three are keyed in by hand** — confirmed 2026-08-14 with Luz, who
+  handles GMX policies at the office. The review screen already has editable
+  inputs for all three, and `postPremium` enables off the *typed* premium, so
+  a hand-entered prima posts to the ledger exactly like a parsed one. No code
+  change was needed to support this; it is a process decision, recorded here
+  because the parser's own note now instructs the reviewer accordingly.
+
+  > **A blank vigencia is silently permanent.** `Policy.policyTo` is nullable
+  > and the renewals window query filters `policyTo: { gte, lte }`
+  > (`renewals.service.ts`), so a policy confirmed without one **never matches
+  > and never gets a renewal notice** — no error, no warning, and nothing
+  > later notices. This is why the parser's note names the consequence instead
+  > of just listing the missing fields.
+
+An excluded catastrophic risk is recorded as excluded **in the risk label**
+(`Terremoto o erupción volcánica — Sección Edificio: EXCLUIDO`) with a null
+amount, never as `0`: a coverage insured for zero and an excluded coverage are
+the same number and very different facts, and `ParsedCoverage` has no field
+for the distinction.
+
+## A.N.A. ships two unrelated faces too
+
+`A.N.A. Compañía de Seguros` is the Rosarito office's tourist auto book. Same
+split as GMX, different reason: GMX ships two *documents about one policy*,
+A.N.A. ships two *products*.
+
+| | **AUTOMOBILE** (`SPECIAL POLICY FOR TOURISTS`) | **DRIVER´S POLICY** (the office says *licencia*) |
+|---|---|---|
+| Insures | a specific car | up to five named drivers, whatever they drive |
+| Vehicle table | `ITEM / YEAR / MAKE / BODY / SERIAL No. / PLATES` | **none** |
+| Insured | one `INSURED` cell | numbered `POLICY HOLDER` list |
+| Value columns | one (`LIMIT OF LIABILITY`) | two (`SUM INSURED`, `PREMIUM`) |
+| Sections | 9, numbered | 6, unnumbered, **in a different order** |
+| Parser | `parseAnaAutomobile` | `parseAnaDriverPolicy` |
+
+Selected by `isAnaDriverPolicy` on the title band.
+
+The **four automobile products** the office sells — amplia and responsabilidad
+civil, each annual or by-the-day — are the **same layout with different
+numbers**. "Amplia" prints a vehicle value and `COVERED` on sections 1–2;
+"resp. civil" prints `0.00` and `EXCLUDED`. That is data, not a layout, so
+there is one parser rather than four.
+
+Things worth knowing before touching the ANA parsers:
+
+- **These are born-digital portal PDFs**, so `pdftotext -layout` returns exact
+  glyphs and exact columns. The driver's policy parser uses that: `SUM
+  INSURED` and `PREMIUM` print the same shape (`100,000.00 usd.` /
+  `18.70 usd.`) with no per-row label, so **horizontal position is the only
+  thing that separates them**. The split is computed from the header's own
+  column offsets rather than hardcoded, because they shift between products.
+  If a scan ever arrives without column fidelity, every amount is reported as
+  a sum insured and the reviewer is told the split failed.
+- **The money row is read positionally, not by finding six amounts.** An
+  unused `DISCOUNT` prints as a bare `-`, so an "amounts in order" reading
+  shifts every value one column left on a discounted policy. The parser
+  requires exactly six whitespace-separated cells or reports the row unread.
+- **Each PDF prints its face two or three times** (ORIGINAL, AGENT COPY, then
+  a summary receipt and three travel ID cards), and the pipeline concatenates
+  every page before parsing. The coverage walk is bounded to the first copy
+  and the driver list to the first `POLICY HOLDER` block. Unbounded, the
+  licencia returns the same person three times — which reads as a
+  three-driver policy, not as a bug, so nothing downstream would catch it.
+- **Two five-digit numbers sit in the header band** and only one is the agent
+  clave: the other is the agent's own postal code
+  (`ROSARITO, BAJA CALIFORNIA 22710`). Likewise the agent's street address
+  reads `BENITO JUAREZ 25 No.50 INT 38`, three lines above the `No.` cell that
+  holds the policy number — hence the two-space floor after `No.`.
+- **Sections 6–8 print a PREMIUM where the others print a limit.** $40 is what
+  legal aid *cost*, not a $40 liability limit, so it lands on
+  `ParsedCoverage.premium` (a field GMX never fills) and gets its own column
+  on the review screen. Adding the two together would be meaningless.
+- **`coveragePeriodDays` matters here and nowhere else.** A.N.A. sells 3- and
+  4-day policies. `Policy.coveragePeriodDays` defaults to 365, so a weekend
+  policy left at the default sits in the renewals window a year out. The term
+  is derived from the two dates and cross-checked against the printed `DAYS`
+  cell; a disagreement is noted rather than resolved.
+
+Exclusions follow the GMX rule — recorded in the risk label
+(`MATERIAL DAMAGE — VEHICLE: EXCLUDED`) with a null amount, never as `0`. It
+matters more here: a responsabilidad-civil policy prints `0.00` for material
+damage, so the two are visually identical on the page.
+
+### Vehicles and drivers
+
+A.N.A. is the first provider whose face carries either, so confirm now writes
+`Vehicle` and `InsuredDriver` rows alongside the `Policy`
+(`applyVehiclesAndDrivers`). The parsed values are stored on the document as
+`extractedVehiclesJson` / `extractedDriversJson` and shown read-only in the
+review queue, so a misread VIN is catchable before it is applied.
+
+Both inserts skip a row that already exists on the policy, matched on the
+identifier the document prints — VIN then plate for a vehicle (A.N.A.'s
+TRAILER and TOWING slots have no VIN), licence number then name for a driver.
+The case that forces this is confirming a **renewal** onto an existing policy:
+a blind insert leaves the customer with the same VIN listed twice and no way
+to tell which row the renewal belongs to.
+
+Nothing is ever updated or deleted there. A vehicle whose plate changed lands
+as a second row for a human to reconcile — the safe half of the mistake, since
+an overwrite would destroy the only record of what was insured last term.
+
+The vehicle table is parsed **by token role, not by column offset**, because
+`BODY` is the cell that wraps: `PACIFICA` is one token and `GENESIS SEDAN` is
+two, so a fixed token count reads the VIN out of the wrong slot on the second.
+The 17-character VIN is the anchor and `BODY` is whatever sits between the
+make and it.
+
 ## What the parser reads, and the field it cannot
 
 `ParsedPolicy` fields are all nullable on purpose: each carrier prints a
@@ -145,6 +343,12 @@ insured, broker (→ `Policy.agentName`), legal address, ZIP, `policyFrom` /
 per-coverage table (risk, insured amount, deductible, loss participation)
 preserved verbatim.
 
+Read from an A.N.A. face: all of the above except additional insured and
+broker parens, **plus** the premium (A.N.A. prints it — see below), the policy
+fee, the total, the term in days, the vehicle table, and the named drivers
+with their US licence numbers. The tax and the agent clave have no column in
+the schema and ride in the notes.
+
 > **The GMX certificate carries no premium.** Not "sometimes missing" — the
 > document does not have the figure. It lives on GMX's **separate `recibo`
 > PDF**. The parser leaves `netPremium` / `policyFee` / `brokerFee` / `total`
@@ -157,20 +361,92 @@ This is also why confirm never overwrites an existing `Policy.netPremium`
 with null: the certificate not carrying a premium is not evidence that the
 premium is gone.
 
+A.N.A.'s faces do print one — the `DISCOUNT / PREMIUM / POLICY FEE / TAX /
+LOCAL TAX / TOTAL` row is on the same page — so an ANA document reaches the
+review queue with `netPremium` populated and `postPremium` already ticked.
+
+Four of those six cells are stored: `PREMIUM` → `netPremium`, `POLICY FEE` →
+`policyFee`, `TAX` → `tax` (`extractedTax` on the document, `Policy.tax` on
+confirm), `TOTAL` → `total`. `DISCOUNT` and `LOCAL TAX` are reported as notes
+instead:
+
+- **`DISCOUNT`** has no column, and it prints as a bare `-` when unused, which
+  is what makes the row positional rather than "find six amounts".
+- **`LOCAL TAX`** is a separate levy and is deliberately **not** summed into
+  `tax`. Folding it in would produce an IVA figure that no longer divides back
+  to a rate, which is the reason to store it at all. It reads 0.00 on every
+  A.N.A. policy seen so far; a non-zero one raises
+  *"impuesto local N no capturado"* and means `total` will not reconcile
+  against `netPremium + policyFee + tax`.
+
+`Policy.taxRate` is left null by confirm. A.N.A. prints the IVA **amount**, not
+the rate, and back-dividing one would mint a rate the document never stated —
+the capture form resolves it from the line of business instead
+(`PolicyType.taxRate`, see `apps/api/src/policies/premium.ts`). The figures do
+agree: 298.61 + 30.00 taxed at 8% is 26.29, totalling 354.90, asserted in
+`policy-parser.spec.ts`.
+
 Deductible and loss participation are stored as **strings** (`"5%"`, `"20%"`,
 `"USD 1,000"`) — they are printed as a mix of percentages, currency amounts
 and free text, and normalising them would lose the distinction.
 
+## Policy type and carrier
+
+Confirm sets `Policy.policyTypeId` and `Policy.insuranceProviderId` from what
+the parser read.
+
+| document | `policyTypeName` |
+|---|---|
+| ANA `AUTOMOBILE` | `AUTO` |
+| ANA `DRIVER´S POLICY` | `LICENCIAS` |
+| GMX caratula **and** especificación | `MULT` |
+
+The parser emits a **name**, never an id — it is a pure function over text and
+must not reach for the database, so `resolveLookups()` in the service turns the
+name into a foreign key. A renamed lookup row is then a data change rather than
+a parser change.
+
+**Resolve, never create.** A missing `policy_types` row means a human deleted
+it, and silently recreating it would undo that with no record. The field stays
+null and the reviewer adds the row through the lookups screen. An explicit
+`policyTypeId` / `insuranceProviderId` on the confirm payload always wins.
+
+Two judgement calls worth recording:
+
+- **GMX is `MULT`, not `INCENDIO`.** The caratula's own header reads "Multiple
+  Policy / Home" and the especificación is "PVL Hogar" — one product, two
+  artifacts. `MULT` is the live row carrying 769 of them; `INCENDIO` is
+  fire-only and no policy in the book has ever used it.
+- **The parser's provider code is not the carrier's row name.** The office's
+  book is filed under `ANA SEGUROS`, so `PROVIDER_ROW_NAME` maps `ANA` onto it.
+  A bare `ANA` row with 1 policy also existed and is merged away by
+  `20260815160000_policy_type_repair`.
+
+> **Deleting a lookup row used to be silent data loss.** `policies.policyTypeId`,
+> `policies.insuranceProviderId` and `claims.adjusterId` are all
+> `ON DELETE SET NULL`, and the lookups screen deleted unconditionally — so the
+> delete returned 200 and blanked the field on every row that used it. That is
+> how `M_EMPR` vanished and left 5 policies with no ramo, found months later by
+> querying. All three deletes now refuse while the row is in use, naming it and
+> the count. See `assertLookupUnused` and BACKLOG §2.1.
+
 ## Confirm: what actually gets written
 
 Per confirmed document, in order:
 
 1. **The `Policy` row** — updated if a policy was matched, created under the
    picked customer if not. Only non-null `extracted*` fields are written; null
-   never overwrites existing data.
+   never overwrites existing data. `policyTypeId` and `insuranceProviderId` are
-2. **A `PolicyDocument`** — the source PDF is streamed into the policy's
+   resolved first (above) and left untouched when unresolvable, so an existing
-   storage namespace and attached, so the paperwork stays with the policy.
+   policy never loses a type or carrier it already had.
-3. **Optionally a `Transaction`** — `INSURANCE` domain, negative amount
+2. **`Vehicle` and `InsuredDriver` rows** — for the providers whose face
+   carries them (A.N.A.; never GMX Hogar), skipping any that already exist on
+   the policy. See *Vehicles and drivers* above.
+3. **A `PolicyDocument`** — the source PDF is streamed into the policy's
+   storage namespace and attached, so the paperwork stays with the policy. Its
+   `documentType` is named after whichever parser claimed the page
+   (`ANA_POLICY`, `GMX_POLICY`).
+4. **Optionally a `Transaction`** — `INSURANCE` domain, negative amount
    (a charge), `captureSource: "OCR"`, `captureRef` = the document id.
 
 The ledger write is **opt-in twice over**: staff must tick `postPremium`
@@ -210,20 +486,71 @@ feature is disabled.
 
 ## Tests
 
-`apps/api/src/policy-ocr/parsers/policy-parser.spec.ts` — 8 cases, all
+`apps/api/src/policy-ocr/parsers/policy-parser.spec.ts` — 58 cases against
-against verbatim text extracted from one real document,
+verbatim text extracted from five real documents, indentation and blank lines
-`HC_Folio_000767_Traduccion.pdf`: provider detection from the wordmark and
+included (the column positions are what the parser reads, so a cleaned-up
-from the footer URL, the header fields, every coverage row off the second
+fixture would test nothing — and on A.N.A.'s driver's policy the offsets are
-page, the deductible/loss-participation strings, the missing-premium note,
+literally the only thing separating two columns).
-the broker line with the agent-number parens absent, and a page with no GMX
+
-signal at all (which must yield no provider rather than a bad guess).
+From `HC_Folio_000767_Traduccion.pdf` (caratula): provider detection from the
+wordmark and from the footer URL, the header fields, every coverage row off
+the second page, the deductible/loss-participation strings, the
+missing-premium note, the broker line with the agent-number parens absent,
+and a page with no GMX signal at all (which must yield no provider rather
+than a bad guess).
+
+From `007_LGS-HGMX_07006957_01_0-CondicionesParticulares.pdf`
+(especificación): the differently-grouped policy number, the risk location
+read across its wrapped line, the empty `Asegurado Adicional` cell that must
+not capture the next line, the absent-by-design fields, currency taken from
+the USD limits rather than the M.N. sublimits in the body prose, a limit
+split under `Edificio` / `Contenidos` sub-labels, a limit printed on the
+label's own line, a deductible stated as a sentence *above* its limit, a
+sublimit block whose amount sits after both a blank line and a page break,
+the excluded earthquake coverage, and the hydrometeorological deductible and
+coinsurance pulled from their own per-zone block.
+
+Plus four cases in `apps/api/src/policies/lookup-delete-guard.spec.ts` pinning
+the refusal that stops a lookup delete from silently blanking the rows that use
+it, and four in the parser suite on the policy-type NAME each document yields.
+
+From the three A.N.A. PDFs: brand detection (and that GMX's layout rules
+cannot claim an ANA page), the header band, DD MM YYYY read out of three
+separate column cells, the six money cells with `DISCOUNT` printed as a bare
+`-`, the vehicle row with a one-word and a two-word `BODY` cell, the empty
+TRAILER/TOWING slots, the agent street number and postal code that must *not*
+be read as the policy number and clave, the declared values labelled by item
+slot, the `$500.00` inside the deductible sentence that is not a sum insured,
+the per-person/per-accident split in both of its printed forms, an add-on's
+figure recorded as a premium, section 9's parenthesised limit, the by-the-day
+term, the excluded sections, the column-position split on the driver's policy,
+its different section order, and — for both faces — that a doubled or tripled
+input yields one set of coverages and one driver rather than one per copy.
+
+`apps/api/src/policy-ocr/name-matcher.spec.ts` — 21 cases on the customer name
+suggestions, every fixture name lifted from the real book: the reversed name,
+the printed middle name, the exact row outranking the row that merely contains
+it, the joint account reached from one spouse (and refused when only given
+names are printed), the Spanish double surname with the comma in either place,
+the 54 rows with no comma at all, the `(SIN NOMBRE)` placeholder, a bare shared
+surname, and the page-sized blob. Four more in
+`policy-matcher.service.spec.ts` pin the wiring: suggestions on the zero-hit
+and unreadable-number paths, no book read at all when the policy number hits,
+and one book read across a batch.
+
+Four of the GMX cases are regression tests for ways the parser can silently attach
+the *wrong* value rather than none — a neighbouring coverage's prose read as
+a deductible, the page-level `DEDUCIBLES:` paragraph read as one, a coverage
+named after a wrapped prose tail, and one section's per-zone deductible
+adopted by the coverage above it. Each was a real defect caught by running
+the parser against the full ten-page document.
 
 ## Not built
 
-- **Only GMX.** The dispatcher (`detectPolicyProvider`) is a table of
+- **GMX and A.N.A. only.** The dispatcher (`detectPolicyProvider`) is a table
-  `[provider, pattern]` pairs plus a `parsers` map, so adding ANA or Qualitas
+  of `[provider, pattern]` pairs plus a `parsers` map, so adding Qualitas is a
-  is a parser function and two entries — but no other carrier's layout has
+  parser function and two entries — but no other carrier's layout has been
-  been seen yet, and guessing at one produces a parser nobody can verify.
+  seen yet, and guessing at one produces a parser nobody can verify.
 - **The `recibo` PDF.** Reading the premium off GMX's separate receipt
   document, and pairing it to the certificate it belongs to, is the obvious
   next piece. It is what would let `postPremium` stop being a manual tick.

migration/backfill_policy_premium_breakdown.py

@@ -0,0 +1,249 @@
+"""
+Recovers the premium breakdown the original policy transform dropped.
+
+`transform_policies.py` modeled prima neta, derecho de póliza and comisión and
+nothing else, which lost two things from every migrated policy:
+
+  1. RECARGO — the financing surcharge on a policy paid in more than one
+     exhibición, plus the whole second money row (`p_neta_2`, `recargo_2`,
+     `d_pol_2`, `com_2`) that a semestral policy carries because each payment
+     is priced separately. These were not deleted, they were swept into
+     `policies.coveragesJson` as loose strings alongside the real coverages —
+     unqueryable, and mislabeled as coverage amounts.
+
+  2. FORMA PAGO — dropped outright. The column was marked "consumed" by the
+     transform's coverage sweep but never written to any column, so it exists
+     nowhere in the platform database. It is the field that decides whether a
+     recargo is legitimate on a row at all, so it cannot be inferred back from
+     the money.
+
+The transform has been fixed in the same commit, so a full `run_all.py` now
+produces all of this directly. This script exists for a database that must not
+be re-imported: it reads the same staged Parquet and patches in place.
+
+What it does NOT do: invent IVA or the printed TOTAL. Those were never columns
+in the home tables — they were unbound calculated controls on the Access form —
+so there is genuinely nothing to recover, and both stay null until a human
+edits the policy. The app computes them (apps/api/src/policies/premium.ts).
+
+Idempotent, and never overwrites a non-null value: a figure a human has since
+corrected in the app wins over the legacy one.
+
+    ./.venv/bin/python backfill_policy_premium_breakdown.py --env dev
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+
+import pandas as pd
+
+from dbenv import connect
+from sync import parse_mode
+
+STG = Path(__file__).parent / "output" / "stg_seguros"
+LEGACY_DB = "SEGUROS 16_be"
+NULL = "∅"
+
+# Legacy column -> what it is, per source table. Only the tables that actually
+# carry a breakdown appear; the auto tables have no recargo and no second row.
+HOME_TABLES = ("mult", "incendio", "m_empr")
+
+# Keys the transform used to dump into coveragesJson that are now real columns.
+# Stripped once migrated so the blob stops pretending they are coverages.
+MIGRATED_COVERAGE_KEYS = (
+    "recargo", "recargo_2", "p_neta_2", "d_pol_2", "com_2",
+)
+
+_FREQ = {
+    "ANNUAL": "ANNUAL",
+    "ANUAL": "ANNUAL",
+    "SEMESTRAL": "SEMIANNUAL",
+    "TRIMESTRAL": "QUARTERLY",
+    "MENSUAL": "MONTHLY",
+    "CONTADO": "SINGLE",
+}
+
+
+def s(v):
+    if v is None or pd.isna(v):
+        return None
+    v = str(v).strip()
+    return None if v in ("", NULL) else v
+
+
+def dec(v):
+    v = s(v)
+    if v is None:
+        return None
+    try:
+        return Decimal(v.replace(",", ""))
+    except (InvalidOperation, ValueError):
+        return None
+
+
+def freq(v):
+    return _FREQ.get((s(v) or "").upper())
+
+
+def load(name):
+    df = pd.read_parquet(STG / f"{name}.parquet").sort_values("_row_num").reset_index(drop=True)
+    for c in df.columns:
+        if c != "_row_num":
+            df[c] = df[c].astype("string").str.strip()
+    return df
+
+
+def main():
+    env, _sync_mode = parse_mode()
+
+    # Fails closed rather than reporting a clean run over nothing: an empty
+    # staging directory and a policy set with no recargo look identical from
+    # the database side, and "0 rows updated" would read as success.
+    if not STG.exists():
+        print(f"[policy-premium] staged Parquet missing at {STG} — run extract/load first.")
+        return 3
+
+    conn = connect(env)
+    c = conn.cursor()
+    print(f"[policy-premium] target env: {env}")
+
+    # Every policy that came from the insurance ETL, keyed by provenance. The
+    # id is needed to reach the installments, coveragesJson to strip the keys.
+    c.execute(
+        "SELECT legacySourceTable, legacyId, id, coveragesJson "
+        "FROM policies WHERE legacySourceDb = %s AND legacyId IS NOT NULL",
+        (LEGACY_DB,),
+    )
+    by_key = {(t, lid): (pid, cov) for t, lid, pid, cov in c.fetchall()}
+    print(f"  {len(by_key)} migrated polic(ies) in the target database")
+
+    pol_updates = []       # (surcharge, paymentFrequency, coveragesJson, policyId)
+    inst_updates = []      # (netPremium, surcharge, policyFee, commission, policyId, seq)
+    seen_tables = 0
+
+    for table in HOME_TABLES + (
+        "tabla_autos", "tabla_autos_ampl", "tabla_autos_limit",
+        "tabla_autos_ampl_r", "tabla_autos_rc_r", "mca2", "licencias",
+    ):
+        path = STG / f"{table}.parquet"
+        if not path.exists():
+            continue
+        seen_tables += 1
+        df = load(table)
+        home = table in HOME_TABLES
+
+        for _, row in df.iterrows():
+            key = (table, str(int(row["_row_num"])))
+            hit = by_key.get(key)
+            if not hit:
+                continue
+            pid, cov_raw = hit
+
+            surcharge = dec(row.get("recargo")) if home else None
+            frequency = freq(row.get("forma_pago"))
+
+            # Strip the now-modeled keys out of the coverage blob. Rewritten
+            # only when something actually changes, so a policy whose blob a
+            # human has edited is left byte-identical.
+            cov_new = None
+            if cov_raw:
+                try:
+                    cov = json.loads(cov_raw) if isinstance(cov_raw, str) else cov_raw
+                except (TypeError, ValueError):
+                    cov = None
+                if isinstance(cov, dict):
+                    kept = {k: v for k, v in cov.items() if k not in MIGRATED_COVERAGE_KEYS}
+                    if len(kept) != len(cov):
+                        cov_new = json.dumps(kept, ensure_ascii=False) if kept else None
+
+            if surcharge is not None or frequency is not None or cov_new is not None:
+                pol_updates.append((surcharge, frequency, cov_new, cov_new is not None, pid))
+
+            # Per-payment breakdown. Slot 1 is the unsuffixed money row, slot 2
+            # the _2 twin; the auto tables have a single slot and no recargo.
+            if home:
+                slots = [
+                    (1, "p_neta", "recargo", "d_pol", "com"),
+                    (2, "p_neta_2", "recargo_2", "d_pol_2", "com_2"),
+                ]
+            else:
+                pn = "prima1" if table == "mca2" else "prima_neta"
+                dp = "d_poliza1" if table == "mca2" else "d_poliza"
+                slots = [(1, pn, None, dp, None)]
+
+            for seq, pn, rc, dp, cm in slots:
+                vals = (
+                    dec(row.get(pn)) if pn else None,
+                    dec(row.get(rc)) if rc else None,
+                    dec(row.get(dp)) if dp else None,
+                    dec(row.get(cm)) if cm else None,
+                )
+                if all(v is None for v in vals):
+                    continue
+                inst_updates.append((*vals, pid, seq))
+
+    if not seen_tables:
+        print(f"[policy-premium] no policy tables staged under {STG} — nothing to do.")
+        return 3
+
+    # COALESCE on every target: a column a human has already filled in the app
+    # keeps its value, the legacy figure only lands where there is a hole.
+    for surcharge, frequency, cov_new, rewrite_cov, pid in pol_updates:
+        c.execute(
+            "UPDATE policies SET "
+            "  surcharge = COALESCE(surcharge, %s), "
+            "  paymentFrequency = COALESCE(paymentFrequency, %s), "
+            "  coveragesJson = IF(%s, %s, coveragesJson) "
+            "WHERE id = %s",
+            (surcharge, frequency, 1 if rewrite_cov else 0, cov_new, pid),
+        )
+
+    for netp, surch, fee, comm, pid, seq in inst_updates:
+        c.execute(
+            "UPDATE policy_payment_installments SET "
+            "  netPremium = COALESCE(netPremium, %s), "
+            "  surcharge  = COALESCE(surcharge, %s), "
+            "  policyFee  = COALESCE(policyFee, %s), "
+            "  commission = COALESCE(commission, %s) "
+            "WHERE policyId = %s AND sequence = %s",
+            (netp, surch, fee, comm, pid, seq),
+        )
+
+    conn.commit()
+    print(f"  policies    : {len(pol_updates)} row(s) touched")
+    print(f"  installments: {len(inst_updates)} row(s) touched")
+
+    # --- validation ---------------------------------------------------------
+    c.execute("SELECT COUNT(*) FROM policies WHERE surcharge IS NOT NULL AND surcharge <> 0")
+    n_surch = c.fetchone()[0]
+    c.execute("SELECT COUNT(*) FROM policies WHERE paymentFrequency IS NOT NULL")
+    n_freq = c.fetchone()[0]
+    c.execute(
+        "SELECT COUNT(*) FROM policies "
+        "WHERE paymentFrequency IN ('ANNUAL','SINGLE') AND surcharge IS NOT NULL AND surcharge <> 0"
+    )
+    n_bad = c.fetchone()[0]
+    c.execute(
+        "SELECT COUNT(*) FROM policies WHERE coveragesJson IS NOT NULL "
+        "AND JSON_EXTRACT(coveragesJson, '$.recargo') IS NOT NULL"
+    )
+    n_left = c.fetchone()[0]
+
+    print(f"  -> policies with a recargo    : {n_surch}")
+    print(f"  -> policies with a forma pago : {n_freq}")
+    print(f"  -> recargo still in coverages : {n_left}")
+
+    # A surcharge on an annual policy contradicts the rule the capture form
+    # enforces, so it is worth surfacing rather than leaving for someone to
+    # find in a total. It is a warning, not a failure: the books are the books.
+    if n_bad:
+        print(f"  !! {n_bad} annual/contado polic(ies) carry a non-zero recargo — review by hand")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

migration/config.py

@@ -18,6 +18,7 @@ the four Access source files.
 """
 
 import os
+import re
 from pathlib import Path
 
 # The folder holding the four Access source files. Overridable via INGEST_DIR so
@@ -95,3 +96,59 @@ SOURCES = {
         },
     },
 }
+
+
+# --- prior-period archives ----------------------------------------------
+#
+# Legacy ran a year-end *corte*: it summed the closing year, wrote that total
+# back as each customer's Jan-1 BALANCE FORWARD, and started the next year
+# clean. Access keeps the closed year as a whole-database snapshot named for
+# the period it holds — `2025.accdb` is UTILITIES as it stood when 2025 was
+# cut — and the office archives one per year.
+#
+# Only the ledger is staged out of a snapshot. Everything else in it (DATMEX,
+# PROFILE, EFECTIVO, ...) is a year-stale copy of a table the live
+# UTILITIES.accdb already provides, and staging all ~50 of them would triple
+# the extract time to import data we would then have to ignore. DATGRAL comes
+# along solely to check that a NUMid still means the same customer it did that
+# year; see the recycle guard in transform_transactions.py.
+#
+# The cash side is deliberately NOT taken from the snapshot: `EFECTIVO` is a
+# lifetime journal, so the snapshot's copy is a subset of the live one and
+# importing it would double-book every prior-year receipt.
+PERIOD_FILE_RE = re.compile(r"^(\d{4})\.accdb$", re.IGNORECASE)
+PERIOD_TABLES = {"datos2", "DATGRAL"}
+
+
+def period_schema(year: int) -> str:
+    return f"stg_period_{year}"
+
+
+def discover_periods(root: Path) -> dict[str, dict]:
+    """Find every `YYYY.accdb` archive sitting in the ingest folder.
+
+    Discovery is by filename because that is the whole upload contract: the
+    operator drops `2025.accdb` on the Operaciones page and the period is 2025.
+    Nothing inside the file names the year — a snapshot's `datos2` looks
+    identical to the live one — so the name is the only declaration of intent
+    we get, and it is what the allowlist on the upload endpoint enforces.
+    """
+    found: dict[str, dict] = {}
+    if not root.is_dir():
+        return found
+    for path in sorted(root.iterdir()):
+        m = PERIOD_FILE_RE.match(path.name)
+        if not m:
+            continue
+        year = int(m.group(1))
+        found[f"period_{year}"] = {
+            "path": path,
+            "schema": period_schema(year),
+            "exclude": set(),
+            "include": set(PERIOD_TABLES),
+            "period_year": year,
+        }
+    return found
+
+
+SOURCES.update(discover_periods(SOURCE_ROOT))

migration/load_staging.py

@@ -40,6 +40,17 @@ def stage_source(source_name: str, source_cfg: dict, sink) -> None:
     tables = extract.list_tables(cnxn)
     excluded = source_cfg["exclude"]
 
+    # A source may name the only tables it is worth staging. Prior-period
+    # archives do: they are whole-database snapshots, but everything in them
+    # except the ledger is a year-stale copy of a live table, so staging the
+    # rest costs minutes per file to produce data nothing reads.
+    include = source_cfg.get("include")
+    if include is not None:
+        missing = include - set(tables)
+        if missing:
+            print(f"  [WARN] {source_name}: missing expected table(s) {sorted(missing)}", file=sys.stderr)
+        tables = [t for t in tables if t in include]
+
     for table_name in tables:
         if table_name in excluded:
             print(f"  [exclude] {table_name}")

migration/native_guard.py

@@ -0,0 +1,210 @@
+"""
+Refuse a full re-import that would delete platform-native data.
+
+A full `run_all.py` pass truncates and rebuilds every table it owns from the
+Access extract:
+
+    transform_customers.py    customers, customer_legacy_refs
+    transform_properties.py   properties, property_services, service_documents,
+                              trust_accounts
+    transform_policies.py     policies + installments, vehicles, drivers,
+                              beneficiaries, claims, adjusters, policy_types,
+                              insurance_providers
+    transform_transactions.py transactions, type_transactions, exchange_rates
+    transform_bank.py         bank tables
+    blob_extract.py           service_documents, policy_documents
+
+That was harmless while the platform was a read-only mirror of Access: every
+row came from the extract, so wiping and rebuilding lost nothing. It stopped
+being harmless when the platform started minting rows Access has never heard
+of — portal NUMids from the allocator (apps/api/src/customers/numid.service.ts),
+customers created in the staff UI, OCR-captured policies, app-booked ledger
+rows, uploaded documents. None of those come back.
+
+`--sync` already avoids all of it: it upserts legacy rows against the existing
+refs and leaves everything else alone. So this guard does not try to teach the
+full path to preserve anything — it stops the full path when there is something
+to preserve, and points at the additive one.
+
+    python native_guard.py --env prod          # report only, exit 3 if blocking
+    python run_all.py --env prod --stage       # runs this first, refuses on 3
+    python run_all.py --env prod --force-full  # ignore the guard (deletes them)
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+import pandas as pd
+
+from dbenv import connect
+
+STG = Path(__file__).parent / "output"
+
+# Exit code the orchestrator looks for. Distinct from 1 so a connection failure
+# or a bad query is not silently read as "native rows found".
+BLOCKED = 3
+
+# transform_customers.py mints these when a legacy row carries no id of its own.
+# They are regenerated by every full pass, so they are legacy-owned, not native.
+SYNTHETIC_REF_PREFIXES = ("rownum_", "insrow_")
+
+# App-uploaded documents are stored as `<prefix>/<parent>/<uuid>.<ext>`, while
+# blob_extract writes `<prefix>/<parent>/<stagedtable>_<row>_<col>.<ext>`.
+# service_documents carries no provenance column, so the key shape is the only
+# signal available — approximate, and reported as such. Matched in MySQL rather
+# than in Python so the whole scan stays one round trip per table.
+UUID_KEY_SQL = "/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\."
+
+
+def staged_legacy_ids() -> dict[str, set[str]] | None:
+    """The ids Access will re-create, per source system.
+
+    None when the staged Parquet is absent — which is not the same as "no legacy
+    ids". Returning an empty set there would mark all 1,171 refs as native and
+    block every run; returning None lets the caller say "cannot verify" instead.
+    """
+    sources = {"utilities": "stg_utilities", "insurance": "stg_seguros"}
+    out: dict[str, set[str]] = {}
+    for system, folder in sources.items():
+        path = STG / folder / "datgral.parquet"
+        if not path.exists():
+            return None
+        df = pd.read_parquet(path, columns=["num_id"])
+        ids = set()
+        for v in df["num_id"].astype("string"):
+            if v is None or pd.isna(v):
+                continue
+            v = str(v).strip()
+            if v.endswith(".0"):  # some numeric ids serialize as "521.0"
+                v = v[:-2]
+            if v and v != "0":
+                ids.add(v)
+        out[system] = ids
+    return out
+
+
+def native_refs(cur, staged: dict[str, set[str]] | None) -> tuple[int, list[str]]:
+    """Legacy refs with no counterpart in the Access extract.
+
+    This is the check that catches an allocated portal NUMid: the customer holds
+    a perfectly ordinary-looking (utilities, DATGRAL, '1172') ref, so "customer
+    has no refs" does not see it. Only comparing against staging does.
+    """
+    cur.execute(
+        "SELECT sourceSystem, legacyId FROM customer_legacy_refs ORDER BY sourceSystem, legacyId"
+    )
+    rows = cur.fetchall()
+    if staged is None:
+        return 0, []
+
+    found = []
+    for system, legacy_id in rows:
+        if legacy_id.startswith(SYNTHETIC_REF_PREFIXES):
+            continue
+        known = staged.get(system)
+        # An unknown source system has no extract to compare against, so it
+        # cannot be re-created either — treat it as native rather than ignoring.
+        if known is None or legacy_id not in known:
+            found.append(f"{system}/{legacy_id}")
+    return len(found), found
+
+
+def scan(conn) -> tuple[list[tuple[str, int, str]], bool]:
+    """(label, count, detail) per source of native rows, plus whether staging
+    was available to verify the refs."""
+    cur = conn.cursor()
+    staged = staged_legacy_ids()
+    findings: list[tuple[str, int, str]] = []
+
+    ref_count, ref_examples = native_refs(cur, staged)
+    if ref_count:
+        shown = ", ".join(ref_examples[:8])
+        more = f" (+{ref_count - 8} more)" if ref_count > 8 else ""
+        findings.append(("customer_legacy_refs", ref_count, f"{shown}{more}"))
+
+    cur.execute(
+        "SELECT COUNT(*) FROM customers c"
+        " WHERE NOT EXISTS (SELECT 1 FROM customer_legacy_refs r WHERE r.customerId = c.id)"
+    )
+    n = cur.fetchone()[0]
+    if n:
+        findings.append(("customers", n, "created in the staff UI, no legacy ref"))
+
+    # Every transform writes legacyId on what it loads, so a NULL is the app's.
+    for table, detail in (
+        ("transactions", "booked in the app (captura, OCR, manual)"),
+        ("policies", "created in the app or captured by policy OCR"),
+        ("properties", "created in the app"),
+        ("vehicles", "created in the app"),
+        ("bank_transactions", "booked in the chequera"),
+    ):
+        cur.execute(f"SELECT COUNT(*) FROM {table} WHERE legacyId IS NULL")
+        n = cur.fetchone()[0]
+        if n:
+            findings.append((table, n, detail))
+
+    # blob_extract always writes originalColumn; the app never does.
+    cur.execute("SELECT COUNT(*) FROM policy_documents WHERE originalColumn IS NULL")
+    n = cur.fetchone()[0]
+    if n:
+        findings.append(("policy_documents", n, "uploaded in the app"))
+
+    cur.execute("SELECT COUNT(*) FROM service_documents WHERE storageKey REGEXP %s",
+                (UUID_KEY_SQL,))
+    n = cur.fetchone()[0]
+    if n:
+        findings.append(("service_documents", n, "uploaded in the app (key shape, approximate)"))
+
+    return findings, staged is not None
+
+
+def report(findings, staged_ok: bool, env: str) -> int:
+    print(f"=== Verificación de datos nativos (env={env}) ===", flush=True)
+
+    if not staged_ok:
+        print(
+            "  ! No hay Parquet en migration/output, así que no se pueden verificar\n"
+            "    los refs contra el extracto de Access. Ejecute con --stage.",
+            flush=True,
+        )
+
+    if not findings:
+        print("  Sin filas nativas. Una reimportación completa no destruye nada.", flush=True)
+        return 0 if staged_ok else BLOCKED
+
+    total = sum(n for _, n, _ in findings)
+    print(f"  {total} filas existen SÓLO en la plataforma y se perderían:", flush=True)
+    for label, n, detail in findings:
+        print(f"    {n:>7}  {label:<22} {detail}", flush=True)
+    print(
+        "\n  Una reimportación completa vacía estas tablas y las reconstruye desde\n"
+        "  Access, que no conoce ninguna de estas filas.\n"
+        "\n  Use la sincronización aditiva (run_all.py --sync), que respeta lo\n"
+        "  capturado en la plataforma. Para reimportar de todos modos y BORRARLAS,\n"
+        "  ejecute run_all.py --force-full.",
+        flush=True,
+    )
+    return BLOCKED
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    ap.add_argument("--env", default="dev")
+    args = ap.parse_args()
+
+    conn = connect(args.env)
+    try:
+        findings, staged_ok = scan(conn)
+    finally:
+        conn.close()
+
+    raise SystemExit(report(findings, staged_ok, args.env))
+
+
+if __name__ == "__main__":
+    main()

migration/run_all.py

@@ -15,6 +15,17 @@ Then:
   ./.venv/bin/python run_all.py --env dev            # data only (staging already present)
   ./.venv/bin/python run_all.py --env prod --stage   # re-extract from Access first, then load
 
+A full pass truncates and rebuilds every table it owns from the Access extract,
+so anything the platform minted itself — allocated portal NUMids, customers
+created in the staff UI, OCR-captured policies, app-booked ledger rows, uploaded
+documents — is destroyed. native_guard.py runs first and refuses when the target
+database holds any of it; --force-full overrides and deletes them.
+
+--sync swaps the truncate+rebuild steps for the additive upsert ones. It reads
+the same staged Parquet, so it needs --stage too unless a previous run left
+migration/output populated on this machine — which is never true in a
+container, where that directory is part of the image and dies with it.
+
 Reproducing dev -> prod is exactly `--env prod` (plus --stage if the staged
 Parquet isn't present on the machine running it).
 
@@ -48,6 +59,12 @@ STEPS = [
     # touches.
     "backfill_statement_match_fields.py",
     "transform_policies.py",
+    # Premium breakdown (recargo, per-payment figures, forma de pago).
+    # transform_policies.py now writes these directly, so on a full rebuild
+    # this is a no-op that re-asserts them; on a database migrated before the
+    # breakdown existed it is what recovers them out of coveragesJson.
+    # Must follow transform_policies.py, which truncates the installments.
+    "backfill_policy_premium_breakdown.py",
     "transform_transactions.py",
     "prune_empty_customers.py",
     # Seeds the Scotiabank chequera that every SCOTHIA movement is booked into;
@@ -67,6 +84,12 @@ SYNC_STEPS = [
     # touches.
     "backfill_statement_match_fields.py",
     "transform_policies.py",
+    # Premium breakdown (recargo, per-payment figures, forma de pago).
+    # transform_policies.py now writes these directly, so on a full rebuild
+    # this is a no-op that re-asserts them; on a database migrated before the
+    # breakdown existed it is what recovers them out of coveragesJson.
+    # Must follow transform_policies.py, which truncates the installments.
+    "backfill_policy_premium_breakdown.py",
     "transform_transactions.py",
     # Manual-safe prune: drops legacy-owned empties that the customer upsert
     # re-creates from Parquet, but leaves manually-added customers alone.
@@ -78,7 +101,40 @@ SYNC_STEPS = [
 ]
 
 
-def run(cmd: list[str]) -> None:
+# native_guard.py exits with this when the target database holds rows that only
+# exist in the platform. Kept in step with the constant there.
+GUARD_BLOCKED = 3
+
+
+def guard(env: str, force: bool) -> None:
+    """Stop a full pass that would delete platform-native rows.
+
+    Only the full path needs this: --sync upserts legacy rows against the
+    existing refs and leaves everything else alone, so it cannot lose anything.
+    Run after staging, because the guard verifies legacy refs against the staged
+    Parquet and cannot tell an allocated NUMid from an Access one without it.
+    """
+    cmd = [PY, str(HERE / "native_guard.py"), "--env", env]
+    print("+ " + " ".join(cmd), flush=True)
+    r = subprocess.run(cmd)
+    if r.returncode == GUARD_BLOCKED and not force:
+        sys.exit(r.returncode)
+    if r.returncode == GUARD_BLOCKED and force:
+        print(
+            "\n! --force-full: continuando y BORRANDO las filas nativas listadas.\n",
+            flush=True,
+        )
+    elif r.returncode:
+        sys.exit(r.returncode)
+
+
+def run(cmd: list[str], step: int | None = None, total: int | None = None) -> None:
+    # The "[paso i/N] name" marker is a contract with the Operaciones screen,
+    # which parses the last one to show progress. Emitting it here rather than
+    # letting the UI count STEPS itself keeps the two from drifting when a step
+    # is added — the number of steps is only ever stated in this file.
+    if step is not None and total is not None:
+        print(f"[paso {step}/{total}] {Path(cmd[1]).name}", flush=True)
     print("+ " + " ".join(cmd), flush=True)
     r = subprocess.run(cmd)
     if r.returncode:
@@ -92,16 +148,31 @@ def main() -> None:
                     help="re-run the raw staging load first (needs the Access files + mdbtools)")
     ap.add_argument("--sync", action="store_true",
                     help="upsert legacy rows and archive removed legacy rows; preserve manual rows")
+    ap.add_argument("--force-full", action="store_true",
+                    help="run the full truncate+rebuild even when it deletes platform-native rows")
     args = ap.parse_args()
 
-    if args.stage:
+    steps = SYNC_STEPS if args.sync else STEPS
-        run([PY, str(HERE / "load_staging.py"), "--output-dir", str(HERE / "output")])
+    # Staging counts as a step when it runs: it is the slowest part of the pass
+    # (mdbtools re-reads every Access file), so leaving it outside the numbering
+    # would park the Operaciones progress bar at "nothing yet" for minutes.
+    total = len(steps) + (1 if args.stage else 0)
+    offset = 1 if args.stage else 0
 
-    for step in SYNC_STEPS if args.sync else STEPS:
+    if args.stage:
+        run([PY, str(HERE / "load_staging.py"), "--output-dir", str(HERE / "output")],
+            step=1, total=total)
+
+    # Deliberately not counted as a step: it is a precondition, it takes a
+    # second, and the Operaciones progress bar parses those numbers.
+    if not args.sync:
+        guard(args.env, args.force_full)
+
+    for i, step in enumerate(steps, start=1 + offset):
         cmd = [PY, str(HERE / step), "--env", args.env]
         if args.sync:
             cmd.append("--sync")
-        run(cmd)
+        run(cmd, step=i, total=total)
 
     print(f"\n✓ migration complete for env={args.env}")
 

migration/transform_customers.py

@@ -189,6 +189,11 @@ def customer_from_utilities(row, name_index) -> dict:
         customerSince=as_date(row["cliente_desde"]),
         status=as_bool(row["status"]),
         feeAmount=as_decimal(row["fee"]),
+        # DATGRAL.TIPO is the minimum-balance threshold (100/200/300/500 —
+        # 1,017 of 1,172 customers carry one), NOT an identification or account
+        # type as the column name suggests. It reaches the website as
+        # datosfreak.TIPO and is returned to the customer app as `minBalance`.
+        minimumBalance=as_decimal(row["tipo"]),
         updatedAt=NOW,
     )
 
@@ -217,6 +222,7 @@ def customer_from_insurance(row, name_index) -> dict:
         customerSince=None,
         status=1,
         feeAmount=None,
+        minimumBalance=None,
         updatedAt=NOW,
     )
 
@@ -225,7 +231,7 @@ _CUST_COLS = [
     "id", "name", "nameSource", "nameMissing", "addressLine1", "addressLine2", "city", "state", "zipCode",
     "country", "phone", "mobile", "fax", "email", "notes", "identificationType",
     "identificationNumber", "identificationExpiration", "customerSince",
-    "status", "feeAmount", "updatedAt",
+    "status", "feeAmount", "minimumBalance", "updatedAt",
 ]
 
 
@@ -316,7 +322,7 @@ def main() -> None:
             remap[rec["id"]] = stable or rec["id"]
         for rec in customers:
             rec["id"] = remap[rec["id"]]
-            cur.execute(f"INSERT INTO customers ({','.join(f'`{c}`' for c in _CUST_COLS)}) VALUES ({placeholders}) ON DUPLICATE KEY UPDATE name=VALUES(name),nameSource=VALUES(nameSource),nameMissing=VALUES(nameMissing),addressLine1=VALUES(addressLine1),addressLine2=VALUES(addressLine2),city=VALUES(city),state=VALUES(state),zipCode=VALUES(zipCode),country=VALUES(country),phone=VALUES(phone),mobile=VALUES(mobile),fax=VALUES(fax),email=VALUES(email),notes=VALUES(notes),identificationType=VALUES(identificationType),identificationNumber=VALUES(identificationNumber),identificationExpiration=VALUES(identificationExpiration),customerSince=VALUES(customerSince),status=VALUES(status),feeAmount=VALUES(feeAmount),updatedAt=VALUES(updatedAt)", tuple(rec[c] for c in _CUST_COLS))
+            cur.execute(f"INSERT INTO customers ({','.join(f'`{c}`' for c in _CUST_COLS)}) VALUES ({placeholders}) ON DUPLICATE KEY UPDATE name=VALUES(name),nameSource=VALUES(nameSource),nameMissing=VALUES(nameMissing),addressLine1=VALUES(addressLine1),addressLine2=VALUES(addressLine2),city=VALUES(city),state=VALUES(state),zipCode=VALUES(zipCode),country=VALUES(country),phone=VALUES(phone),mobile=VALUES(mobile),fax=VALUES(fax),email=VALUES(email),notes=VALUES(notes),identificationType=VALUES(identificationType),identificationNumber=VALUES(identificationNumber),identificationExpiration=VALUES(identificationExpiration),customerSince=VALUES(customerSince),status=VALUES(status),feeAmount=VALUES(feeAmount),minimumBalance=VALUES(minimumBalance),updatedAt=VALUES(updatedAt)", tuple(rec[c] for c in _CUST_COLS))
         for ref in refs:
             cur.execute("INSERT INTO customer_legacy_refs (id,customerId,sourceSystem,sourceTable,legacyId) VALUES (%s,%s,%s,%s,%s) ON DUPLICATE KEY UPDATE customerId=VALUES(customerId)",
                         (ref[0], remap[ref[1]], ref[2], ref[3], ref[4]))

migration/transform_policies.py

@@ -18,6 +18,17 @@ Design (validated against staged data):
     policies are skipped and counted (required FK).
   - Payment slots: c_1er_pago is the first amount, pago_subsec the recurring
     amount for slots 2-4; efectivo is a cash flag, no_cheque the check ref.
+  - Premium breakdown: a policy paid in more than one exhibicion prices EACH
+    payment separately, which is why the home tables carry the whole money row
+    twice (p_neta/recargo/d_pol/com and their _2 twins). The unsuffixed set is
+    the policy header, the suffixed one belongs to payment 2, and both are
+    written per installment as well. This used to be lost: `recargo` and the
+    _2 columns fell into coveragesJson as loose strings and forma_pago was
+    marked consumed but never written anywhere at all.
+  - IVA and the printed TOTAL are NOT in Access for the home tables. They were
+    unbound calculated controls on the form, so there is nothing to migrate;
+    the app computes them (apps/api/src/policies/premium.ts) from
+    (p_neta + recargo + d_pol) * rate.
   - Any source column not explicitly modeled (coverage amounts: edificio,
     contenidos, robo, cristales, ...) is preserved verbatim in coveragesJson,
     so nothing is lost in consolidation.
@@ -93,20 +104,55 @@ def truthy(v):
     return (s(v) or "0").lower() in {"1", "-1", "true", "si", "sí", "yes", "x"}
 
 
+# Access FORMA PAGO -> PaymentFrequency. The whole staged corpus holds exactly
+# four spellings (ANNUAL 1851, SEMESTRAL 29, semestral 2, CONTADO 1); anything
+# else is left null rather than guessed, because the value decides whether a
+# recargo is legitimate on the row.
+_FREQ = {
+    "ANNUAL": "ANNUAL",
+    "ANUAL": "ANNUAL",
+    "SEMESTRAL": "SEMIANNUAL",
+    "TRIMESTRAL": "QUARTERLY",
+    "MENSUAL": "MONTHLY",
+    "CONTADO": "SINGLE",
+}
+
+
+def freq(v):
+    return _FREQ.get((s(v) or "").upper())
+
+
+def slot_dec(row, slot, key):
+    """One figure of a payment's premium breakdown, or None when the source
+    table has no such column. Deliberately not zero: a zero d_pol on the second
+    payment is a real figure in the books and must stay distinguishable from
+    'this table never had that column'."""
+    col = slot.get(key)
+    return dec(row.get(col)) if col else None
+
+
 # --- per-table config ------------------------------------------------------- #
 # fields: policy column -> source column. installments: list of slot dicts.
 # vehicles: 'trip_underscore' | 'single' | 'mca2' | None. drivers: 'mca2' |
 # 'licencias' | None.
+# `pneta`/`recarg`/`dpol`/`com` on a slot are that payment's own share of the
+# premium. Only the first two payments have one in Access — the form only ever
+# drew the money row twice — so slots 3 and 4 carry none and keep just the
+# amount actually collected.
 HOME_INST = [
-    dict(seq=1, amt="c_1er_pago", cu="moned", d="fecha_pago", ck="no_cheque", cash="efectivo"),
+    dict(seq=1, amt="c_1er_pago", cu="moned", d="fecha_pago", ck="no_cheque", cash="efectivo",
-    dict(seq=2, amt="pago_subsec", cu="moned_2", d="fecha_pago_2", ck="no_cheque_2", cash="efectivo_2"),
+         pneta="p_neta", recarg="recargo", dpol="d_pol", com="com"),
+    dict(seq=2, amt="pago_subsec", cu="moned_2", d="fecha_pago_2", ck="no_cheque_2", cash="efectivo_2",
+         pneta="p_neta_2", recarg="recargo_2", dpol="d_pol_2", com="com_2"),
     dict(seq=3, amt="pago_subsec", cu="moned_3", d="fecha_pago_3", ck="no_cheque_3", cash="efectivo_3"),
     dict(seq=4, amt="pago_subsec", cu="moned_4", d="fecha_pago_4", ck="no_cheque_4", cash="efectivo_4"),
 ]
 HOME_FIELDS = dict(polno="no_poliza", agent="agent", comp="comp", desde="desde", hasta="hasta",
-                   forma="forma_pago", curcol="moned", pneta="p_neta", dpol="d_pol", com="com",
+                   forma="forma_pago", curcol="moned", pneta="p_neta", recarg="recargo",
+                   dpol="d_pol", com="com",
                    liquidada="liquidada", numliq="num_liquidacion", fliq="f_liquida1", renov="renovacion")
-AUTO_SINGLE_INST = [dict(seq=1, amt="total", cu="moneda", d="fecha_pago", ck="no_cheque", cash="efectivo")]
+AUTO_SINGLE_INST = [dict(seq=1, amt="total", cu="moneda", d="fecha_pago", ck="no_cheque", cash="efectivo",
+                         pneta="prima_neta", dpol="d_poliza")]
 
 CONFIGS = {
     "incendio":  dict(ptype="INCENDIO", idcol="num_id", fields={**HOME_FIELDS, "curcol": "moneda"},
@@ -157,7 +203,8 @@ CONFIGS = {
                                   forma="forma_pago", curcol="moneda", pneta="prima_neta", dpol="d_poliza",
                                   total="total", liquidada="liquidada", numliq="num_liquidacion",
                                   fliq="f_liquida1", renov="renovacion"),
-                      inst=[dict(seq=1, amt="total", cu="moneda", d="fecha_pago", ck="no_cheque", cash="efectivo")],
+                      inst=[dict(seq=1, amt="total", cu="moneda", d="fecha_pago", ck="no_cheque",
+                                 cash="efectivo", pneta="prima_neta", dpol="d_poliza")],
                       veh=None, drv="licencias"),
 }
 
@@ -200,6 +247,10 @@ def main():
         consumed = {cfg["idcol"], *F.values()}
         for slot in cfg["inst"]:
             consumed |= {slot["amt"], slot["cu"], slot["d"], slot["ck"], slot["cash"]}
+            # The per-payment premium columns are now modeled, so they must
+            # leave the coveragesJson sweep — otherwise every recargo would be
+            # written twice, once as a column and once as a fake coverage.
+            consumed |= {slot[k] for k in ("pneta", "recarg", "dpol", "com") if slot.get(k)}
 
         for _, row in df.iterrows():
             cid = cust.get(norm_id(row[cfg["idcol"]]))
@@ -237,9 +288,11 @@ def main():
                 dt(row.get(F.get("desde", ""))) if F.get("desde") else None,
                 dt(row.get(F.get("hasta", ""))) if F.get("hasta") else None,
                 dec(row.get(F.get("pneta", ""))) if F.get("pneta") else None,
+                dec(row.get(F.get("recarg", ""))) if F.get("recarg") else None,
                 dec(row.get(F.get("dpol", ""))) if F.get("dpol") else None,
                 dec(row.get(F.get("com", ""))) if F.get("com") else None,
                 dec(row.get(F.get("total", ""))) if F.get("total") else None,
+                freq(row.get(F.get("forma", ""))) if F.get("forma") else None,
                 cur(row.get(F.get("curcol", ""))) if F.get("curcol") else "MXN",
                 s(row.get("observaciones")),
                 json.dumps(cov, ensure_ascii=False) if cov else None,
@@ -255,9 +308,12 @@ def main():
                 pdate = dt(row.get(slot["d"]))
                 if amt is None and pdate is None:
                     continue
+                # Slot breakdown, where the source table has one.
                 insts.append((str(uuid.uuid4()), pid, slot["seq"], amt,
                               cur(row.get(slot["cu"])), pdate, s(row.get(slot["ck"])),
-                              1 if truthy(row.get(slot["cash"])) else 0))
+                              1 if truthy(row.get(slot["cash"])) else 0,
+                              slot_dec(row, slot, "pneta"), slot_dec(row, slot, "recarg"),
+                              slot_dec(row, slot, "dpol"), slot_dec(row, slot, "com")))
 
             # vehicles
             def add_vehicle(make, model, body, engine, plate, year=None, state=None):
@@ -328,16 +384,19 @@ def main():
                        1 if truthy(r["concluido"]) else 0, s(r["resolucion"])))
 
     pol_cols = ("id,policyNumber,customerId,policyTypeId,insuranceProviderId,agentName,policyDate,"
-                "policyFrom,policyTo,netPremium,policyFee,commission,total,currency,observations,"
+                "policyFrom,policyTo,netPremium,surcharge,policyFee,commission,total,paymentFrequency,"
+                "currency,observations,"
                 "coveragesJson,liquidated,liquidationNumber,liquidationDate,legacySourceDb,"
                 "legacySourceTable,legacyId,updatedAt")
-    ph = ",".join(["%s"] * 23)
+    ph = ",".join(["%s"] * 25)
     pol_upsert = (
         f"INSERT INTO policies ({pol_cols}) VALUES ({ph}) ON DUPLICATE KEY UPDATE "
         "customerId=VALUES(customerId),policyNumber=VALUES(policyNumber),policyTypeId=VALUES(policyTypeId),"
         "insuranceProviderId=VALUES(insuranceProviderId),agentName=VALUES(agentName),policyDate=VALUES(policyDate),"
-        "policyFrom=VALUES(policyFrom),policyTo=VALUES(policyTo),netPremium=VALUES(netPremium),policyFee=VALUES(policyFee),"
+        "policyFrom=VALUES(policyFrom),policyTo=VALUES(policyTo),netPremium=VALUES(netPremium),"
-        "commission=VALUES(commission),total=VALUES(total),currency=VALUES(currency),observations=VALUES(observations),"
+        "surcharge=VALUES(surcharge),policyFee=VALUES(policyFee),"
+        "commission=VALUES(commission),total=VALUES(total),paymentFrequency=VALUES(paymentFrequency),"
+        "currency=VALUES(currency),observations=VALUES(observations),"
         "coveragesJson=VALUES(coveragesJson),liquidated=VALUES(liquidated),liquidationNumber=VALUES(liquidationNumber),"
         "liquidationDate=VALUES(liquidationDate),updatedAt=VALUES(updatedAt),archivedAt=NULL")
 
@@ -399,8 +458,9 @@ def main():
 
 
     c.executemany("INSERT INTO policy_payment_installments "
-                  "(id,policyId,sequence,amount,currency,paidDate,checkNumber,isCash) "
+                  "(id,policyId,sequence,amount,currency,paidDate,checkNumber,isCash,"
-                  "VALUES (%s,%s,%s,%s,%s,%s,%s,%s)", insts)
+                  "netPremium,surcharge,policyFee,commission) "
+                  "VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s)", insts)
     c.executemany("INSERT INTO vehicles (id,customerId,policyId,make,model,modelYear,bodyType,"
                   "engineNumber,licensePlate,stateCode,legacySourceTable,legacyId) "
                   "VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s)", vehicles)

migration/transform_transactions.py

@@ -90,6 +90,62 @@ def load(src, name):
     return df
 
 
+def verify_corte(c, year: int) -> None:
+    """Assert legacy's corte identity: SUM(period Y) == BALANCE FORWARD(Y+1).
+
+    This is the whole reason a year can be shown on its own. Legacy closed each
+    year by summing it and writing that total back as every customer's Jan-1
+    opening row for the next one, so if an archive is the right file, complete,
+    and attached to the right customers, its per-customer total lands exactly on
+    the next year's BALANCE FORWARD. A truncated export, a file dropped under
+    the wrong year, or a botched customer match all break the identity loudly
+    here instead of quietly six months from now.
+
+    Reported, never fatal. Legacy publishes on its own schedule, so a handful of
+    customers legitimately drift between the snapshot and the cut — the run that
+    established this reconciled 1,160 of 1,170.
+    """
+    c.execute(
+        """
+        SELECT sums.customerId, sums.total, bf.amount
+        FROM (
+            SELECT customerId, ROUND(SUM(amount), 2) AS total
+            FROM transactions
+            WHERE legacySourceTable = %s AND voidedAt IS NULL
+            GROUP BY customerId
+        ) sums
+        LEFT JOIN (
+            SELECT t.customerId, ROUND(SUM(t.amount), 2) AS amount
+            FROM transactions t
+            JOIN type_transactions tt ON tt.id = t.typeId
+            WHERE tt.nameEn = 'BALANCE FORWARD' AND t.voidedAt IS NULL
+              AND t.transactionDate >= %s AND t.transactionDate < %s
+            GROUP BY t.customerId
+        ) bf ON bf.customerId = sums.customerId
+        """,
+        (f"datos2@{year}", f"{year + 1}-01-01", f"{year + 1}-01-02"),
+    )
+    rows = c.fetchall()
+    matched = mismatched = 0
+    missing = 0
+    drift = Decimal(0)
+    for _cid, total, amount in rows:
+        if amount is None:
+            missing += 1
+            continue
+        if abs(Decimal(str(total)) - Decimal(str(amount))) < Decimal("0.02"):
+            matched += 1
+        else:
+            mismatched += 1
+            drift += abs(Decimal(str(total)) - Decimal(str(amount)))
+    checked = matched + mismatched
+    pct = (100 * matched / checked) if checked else 0
+    print(
+        f"  corte {year} -> BF {year + 1}: {matched}/{checked} match ({pct:.1f}%)"
+        f", {mismatched} off by {drift:,.2f}, {missing} with no BF row"
+    )
+
+
 def main():
     env, sync_mode = parse_mode()
     conn = connect(env)
@@ -112,6 +168,29 @@ def main():
         type_rows.append((tid, en, s(r["espa_ol"]), 0))
         type_map[en.upper()] = tid
 
+    def type_id_for(raw) -> str | None:
+        """Resolve a transaction type, minting one when the lookup lacks it.
+
+        The Access `TYPE OF TRX` table is a stale pick-list, not a constraint —
+        staff free-text straight into DATOS2, so 78 values covering 3,939 rows
+        (BALANCE FORWARD 1,188, ANNUAL FEE 1,116, IZZI 367, ...) appear in the
+        ledger but not the lookup. Leaving those unmapped stored typeId NULL and
+        lost the label outright: nothing else on `transactions` carries the type
+        text, so the row rendered blank and was unrecoverable after migration.
+        Minting from the literal keeps the display string; nameEs stays NULL
+        because only the lookup has translations.
+        """
+        en = s(raw)
+        if not en:
+            return None
+        key = en.upper()
+        tid = type_map.get(key)
+        if tid is None:
+            tid = str(uuid.uuid4())
+            type_rows.append((tid, en, None, 0))
+            type_map[key] = tid
+        return tid
+
     xr = load("stg_utilities", "tipo_hist")
     xr_rows = []
     for _, r in xr.iterrows():
@@ -126,10 +205,11 @@ def main():
     skip_cust = skip_date = skip_dupe = 0
 
     def add(cid, domain, tdate, amount, currency, *, period=None, reference=None,
-            typeid=None, check=None, message=None, src_db=None, src_tbl=None, legacy=None):
+            typeid=None, check=None, message=None, src_db=None, src_tbl=None, legacy=None,
+            outstanding=0):
         tx.append((str(uuid.uuid4()), cid, domain, typeid, tdate, period, reference,
                    amount if amount is not None else Decimal(0), currency, None, check,
-                   message, 0, src_db, src_tbl, legacy))
+                   message, outstanding, src_db, src_tbl, legacy))
 
     # Business key of a real cash payment. `folio` is deliberately excluded: it
     # is a per-table sequential number that collides between EFECTIVO and
@@ -143,12 +223,24 @@ def main():
             s(r["conepto"]),
         )
 
-    def efectivo_like(src, name, domain, custmap, src_db, legacy_tbl, *, seen=None):
+    def efectivo_like(src, name, domain, custmap, src_db, legacy_tbl, *, seen=None,
+                      type_label=None):
         """Load an EFECTIVO-shaped cash ledger.
 
         `seen` (a set) makes the load de-duplicating: keys are added to it as
         rows load, and a row whose key is already present is skipped. That is
         how EFECTIVO_BACKUP contributes only its genuinely-new rows.
+
+        `type_label` names the transaction type for every row. These tables have
+        no type column at all — in Access the type is implied by which table the
+        row lives in — so unlike DATOS2 there is no string to map and typeId came
+        out NULL for all of them.
+
+        That is not merely a blank label. handleGetAccountDetails in
+        my.jorgecuadros.com identifies payments by matching TYPEOFTRX against
+        ('PAYMENT THANK YOU', 'PAYPAL', 'CASH DEPOSIT', 'CHECK DEPOSIT') to reset
+        the running balance in mode=current; an unlabelled payment is not
+        recognised and the balance silently diverges from legacy.
         """
         nonlocal skip_cust, skip_date, skip_dupe
         df = load(src, name)
@@ -166,9 +258,20 @@ def main():
                 skip_date += 1; continue
             add(cid, domain, td, dec(r["monto"], Decimal(0)), cur(r["monedas"]),
                 reference=s(r["folio"]), message=s(r["conepto"]),
+                typeid=type_id_for(type_label),
                 src_db=src_db, src_tbl=legacy_tbl, legacy=str(int(r["_row_num"])))
 
     def fm3(name, legacy_tbl, check_col=None):
+        """FM3 fee streams. Deliberately left unlabelled, unlike EFECTIVO.
+
+        These rows (EFECTIVO FM3 627, CHEQUE FM3 157) also have no type column,
+        but every one of them predates the two periods the site exposes — it
+        allowlists only the current year and the prior year — so none can be
+        matched against a legacy label, and none can reach a customer. Inventing
+        a plausible name like "CHECK DEPOSIT" would feed the payment-detection
+        list in handleGetAccountDetails on nothing but a guess. Leave them NULL
+        until a real mapping is available.
+        """
         nonlocal skip_cust, skip_date
         df = load("stg_utilities", name)
         for _, r in df.iterrows():
@@ -183,21 +286,86 @@ def main():
                 message=s(r["conepto"]), check=s(r[check_col]) if check_col else None,
                 src_db="UTILITIES", src_tbl=legacy_tbl, legacy=str(int(r["_row_num"])))
 
-    def billing(name, legacy_tbl):
+    def billing(name, legacy_tbl, *, src="stg_utilities", skip_numids=None):
-        nonlocal skip_cust, skip_date
+        """Load a DATOS2-shaped billing ledger.
-        df = load("stg_utilities", name)
+
+        `src` names the staging schema, so a prior-period archive
+        (stg_period_2025) loads through this same path: the snapshot's `datos2`
+        is the identical eleven-column shape, one year older.
+
+        NOPAGO is the legacy "still owed" flag. The website reads it directly —
+        `account.statement.php` splits the statement on `NOPAGO = 0` vs
+        `NOPAGO = 1` and renders the latter as the "Outstanding Bills Requiring
+        Attention" table — so dropping it does not merely lose a column, it
+        silently empties that whole section for anyone served off the platform.
+        Only these three tables carry it (76 rows set in DATOS2 today); the
+        EFECTIVO/FM3 cash streams have no such column and stay 0.
+        """
+        nonlocal skip_cust, skip_date, skip_recycled
+        df = load(src, name)
         for _, r in df.iterrows():
-            cid = util_cust.get(norm_id(r["numid"]))
+            numid = norm_id(r["numid"])
+            if skip_numids and numid in skip_numids:
+                skip_recycled += 1; continue
+            cid = util_cust.get(numid)
             if not cid:
                 skip_cust += 1; continue
             td = dt(r["date"])
             if td is None:
                 skip_date += 1; continue
-            tid = type_map.get((s(r["type_of_trx"]) or "").upper())
+            tid = type_id_for(r["type_of_trx"])
             add(cid, "UTILITY", td, dec(r["chargecredit"], Decimal(0)), "MXN",
                 period=s(r["period"]), reference=s(r["refer"]), typeid=tid,
                 check=s(r["cheque"]), src_db="UTILITIES", src_tbl=legacy_tbl,
-                legacy=str(int(r["_row_num"])))
+                legacy=str(int(r["_row_num"])),
+                outstanding=1 if s(r["nopago"]) == "1" else 0)
+
+    skip_recycled = 0
+    recycle_report: list[tuple[int, str, str, str]] = []
+
+    def period_numid_guard(year: int) -> set[str]:
+        """NUMids whose prior-period owner is not today's customer.
+
+        Prior-period rows attach by NUMid and nothing else, so a number the
+        office retired and reissued would file one customer's ledger under
+        another's name — the one error this feature must never make, because it
+        shows a stranger's charges to whoever holds the number now.
+
+        Reuse is real but rare: comparing each archive's DATGRAL against the
+        live one, 13 names moved since 2025 and 40 since 2024. Most are the same
+        customer re-described — a typo fixed (VIKIE -> VICKIE), a spouse added
+        or dropped (STEWART, ALAN R. -> STEWART, ALAN & JENNIFER). A few are
+        genuinely a different household (STRONKS, BOB -> SWEET, DONALD E.).
+
+        Sharing any word of three or more characters separates the two cleanly:
+        a rename keeps the surname, a reissue keeps nothing. Names are compared
+        legacy-to-legacy, archive DATGRAL against live DATGRAL, deliberately not
+        against `customers.name` — that column has been through the blank-name
+        recovery pass, and comparing to it reported 121 drifts where there are
+        13, every extra one a false positive that would have discarded good
+        history.
+        """
+        try:
+            arch = load(f"stg_period_{year}", "datgral")
+            live = load("stg_utilities", "datgral")
+        except (FileNotFoundError, OSError):
+            return set()
+
+        def toks(v) -> set[str]:
+            return {w for w in "".join(ch if ch.isalnum() else " " for ch in (s(v) or "").upper()).split() if len(w) >= 3}
+
+        live_names = {norm_id(r["num_id"]): s(r["nombre"]) for _, r in live.iterrows()}
+        blocked: set[str] = set()
+        for _, r in arch.iterrows():
+            numid = norm_id(r["num_id"])
+            was, now = s(r["nombre"]), live_names.get(numid)
+            if not numid or not was or not now:
+                continue
+            if toks(was) & toks(now):
+                continue
+            blocked.add(numid)
+            recycle_report.append((year, numid, was, now))
+        return blocked
 
     def iva():
         nonlocal skip_cust
@@ -214,17 +382,50 @@ def main():
     # order matters: EFECTIVO is the live table and loads first, so a collision
     # always resolves in its favour.
     cash_seen: set = set()
+    # "CASH DEPOSIT" is not a guess: matching these rows to the live site on
+    # (NUMid, date, amount) resolves to that label unanimously — 66/66 in the
+    # current-year `datosfreak` and 100/100 in the prior-year `2025` table,
+    # which are the only two periods the site exposes.
     efectivo_like("stg_utilities", "efectivo", "UTILITY", util_cust, "UTILITIES",
-                  "EFECTIVO", seen=cash_seen)
+                  "EFECTIVO", seen=cash_seen, type_label="CASH DEPOSIT")
     efectivo_like("stg_utilities", "efectivo_backup", "UTILITY", util_cust, "UTILITIES",
-                  "EFECTIVO_BACKUP", seen=cash_seen)
+                  "EFECTIVO_BACKUP", seen=cash_seen, type_label="CASH DEPOSIT")
     fm3("efectivo_fm3", "EFECTIVO FM3")
     fm3("cheque_fm3", "CHEQUE FM3", check_col="num_cheque")
     billing("datos2", "datos2")
     billing("fee_anual", "FEE ANUAL")
     billing("fee15", "fee15")
     iva()
-    efectivo_like("stg_seguros", "efectivo", "INSURANCE", ins_cust, "SEGUROS 16_be", "EFECTIVO")
+
+    # --- prior periods -----------------------------------------------------
+    #
+    # Legacy kept each closed year in its own table and opened the next one with
+    # a Jan-1 BALANCE FORWARD carrying the closing total. The platform has one
+    # `transactions` table, so the period a row belongs to has to travel with
+    # the row: it rides in legacySourceTable as `datos2@2025`.
+    #
+    # That tag, not the date, is what a year view should filter on. The archives
+    # are not cleanly bounded — 2025's ledger carries ten undated rows and two
+    # dated into 2026 — and legacy itself never filtered by date either: its
+    # reader is `SELECT ... FROM \`2025\``. Keying on provenance reproduces the
+    # legacy period exactly and strands nothing.
+    #
+    # The tag also keeps the unique key safe. legacyId is a positional row
+    # ordinal, so every archive restarts it at 0 and would collide with the live
+    # `datos2` row-for-row if they shared a source-table name.
+    periods = sorted(
+        int(d.name.rsplit("_", 1)[1])
+        for d in STG.glob("stg_period_*")
+        if d.is_dir() and d.name.rsplit("_", 1)[1].isdigit()
+    )
+    for year in periods:
+        billing("datos2", f"datos2@{year}", src=f"stg_period_{year}",
+                skip_numids=period_numid_guard(year))
+    # Same record shape in the seguros DB. Labelled for consistency in the
+    # platform's own UI; unverifiable against the site, which only ever reads
+    # domain='UTILITY', so no customer-facing behaviour depends on it.
+    efectivo_like("stg_seguros", "efectivo", "INSURANCE", ins_cust, "SEGUROS 16_be",
+                  "EFECTIVO", type_label="CASH DEPOSIT")
 
     if sync_mode:
         # Transaction types are rebuilt with fresh uuids each run; resolve them
@@ -243,7 +444,7 @@ def main():
         if new_types:
             c.executemany("INSERT INTO type_transactions (id,nameEn,nameEs,isService) VALUES (%s,%s,%s,%s)", new_types)
         tx = [(t[0], t[1], t[2], (db_types.get(fresh_name.get(t[3])) if t[3] else None), *t[4:]) for t in tx]
-        c.executemany("INSERT INTO transactions (id,customerId,domain,typeId,transactionDate,period,reference,amount,currency,exchangeRate,checkNumber,message,outstanding,legacySourceDb,legacySourceTable,legacyId) VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s) ON DUPLICATE KEY UPDATE customerId=VALUES(customerId),domain=VALUES(domain),typeId=VALUES(typeId),transactionDate=VALUES(transactionDate),period=VALUES(period),reference=VALUES(reference),amount=VALUES(amount),currency=VALUES(currency),checkNumber=VALUES(checkNumber),message=VALUES(message),voidedAt=NULL", tx)
+        c.executemany("INSERT INTO transactions (id,customerId,domain,typeId,transactionDate,period,reference,amount,currency,exchangeRate,checkNumber,message,outstanding,legacySourceDb,legacySourceTable,legacyId) VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s) ON DUPLICATE KEY UPDATE customerId=VALUES(customerId),domain=VALUES(domain),typeId=VALUES(typeId),transactionDate=VALUES(transactionDate),period=VALUES(period),reference=VALUES(reference),amount=VALUES(amount),currency=VALUES(currency),checkNumber=VALUES(checkNumber),message=VALUES(message),outstanding=VALUES(outstanding),voidedAt=NULL", tx)
     else:
         c.execute("SET FOREIGN_KEY_CHECKS=0")
         for t in ("transactions", "type_transactions", "exchange_rates"):
@@ -268,6 +469,7 @@ def main():
     print(f"  skipped (unresolved customer): {skip_cust}")
     print(f"  skipped (unparseable date)   : {skip_date}")
     print(f"  skipped (EFECTIVO_BACKUP dup): {skip_dupe}")
+    print(f"  skipped (reissued NUMid)     : {skip_recycled}")
     print(f"  -> transactions        : {count('transactions')}")
     print(f"     by domain           : {dict(by_dom)}")
     for src, n in by_src:
@@ -276,6 +478,17 @@ def main():
     print(f"  -> exchange_rates      : {count('exchange_rates')}")
     print(f"  orphan transactions (bad customer FK): {orphans}")
     assert orphans == 0, "transaction customer FK invariant failed"
+
+    if recycle_report:
+        print(f"  ! reissued NUMids, prior-period rows NOT imported: {len(recycle_report)}")
+        for year, numid, was, now in recycle_report[:8]:
+            print(f"      {year} NUMid {numid}: '{was}' -> '{now}'")
+        if len(recycle_report) > 8:
+            print(f"      ... {len(recycle_report) - 8} more")
+
+    for year in periods:
+        verify_corte(c, year)
+
     print("  validation: OK")
     conn.close()
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgecuadros-platform",
-  "version": "1.0.7",
+  "version": "1.0.25",
   "private": true,
   "workspaces": [
     "apps/*",

packages/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jorgecuadros/database",
-  "version": "1.0.7",
+  "version": "1.0.25",
   "private": true,
   "main": "generated/client/index.js",
   "types": "generated/client/index.d.ts",

packages/database/prisma/migrations/20260815120000_policy_ocr_ana/migration.sql

@@ -0,0 +1,12 @@
+-- ANA Seguros policy OCR: the vehicle/driver tables and the printed term in
+-- days that ANA's tourist book carries and GMX's property book does not.
+ALTER TABLE `policy_ocr_documents`
+    ADD COLUMN `extractedCoveragePeriodDays` INTEGER NULL,
+    ADD COLUMN `extractedVehiclesJson` JSON NULL,
+    ADD COLUMN `extractedDriversJson` JSON NULL;
+
+-- The parser note trail outgrew VARCHAR(191): a nine-section ANA policy runs
+-- past it routinely, and the notes that got cut were the tail ones — the
+-- "could not read X" warnings the reviewer most needs.
+ALTER TABLE `policy_ocr_documents`
+    MODIFY COLUMN `matchNote` TEXT NULL;

packages/database/prisma/migrations/20260815160000_policy_type_repair/migration.sql

@@ -0,0 +1,55 @@
+-- The policy type the OCR parser read the product as, resolved to a
+-- `policy_types` row at confirm time.
+ALTER TABLE `policy_ocr_documents`
+    ADD COLUMN `extractedPolicyTypeName` VARCHAR(191) NULL;
+
+-- ---------------------------------------------------------------------------
+-- Repair: M_EMPR was deleted from the lookups screen and took its policies'
+-- type with it.
+--
+-- `policies.policyTypeId` is ON DELETE SET NULL, and removePolicyType() had no
+-- in-use guard, so deleting the row silently blanked the field on every policy
+-- referencing it — 5 of them, all from the legacy `m_empr` table. The guard
+-- against a repeat ships in the same change as this migration. What follows
+-- repairs what already happened.
+--
+-- Idempotent on purpose: `policy_types.name` is UNIQUE so the INSERT IGNORE is
+-- a no-op once the row exists, and the UPDATE is scoped to rows that are still
+-- null AND came from that one legacy table, so it can never claim a policy
+-- whose type was blanked for some other reason.
+INSERT IGNORE INTO `policy_types` (`id`, `name`) VALUES (UUID(), 'M_EMPR');
+
+UPDATE `policies` p
+    JOIN `policy_types` pt ON pt.`name` = 'M_EMPR'
+    SET p.`policyTypeId` = pt.`id`
+    WHERE p.`policyTypeId` IS NULL
+      AND p.`legacySourceTable` = 'm_empr';
+
+-- INCENDIO is deliberately NOT recreated. It is the other row the migration
+-- would have produced, but no policy in the book has ever carried it, so
+-- adding it back would only put a dead option in the type picker.
+
+-- ---------------------------------------------------------------------------
+-- Merge the duplicate ANA carrier.
+--
+-- `insurance_providers` holds both "ANA" (1 policy) and "ANA SEGUROS" (738).
+-- They are one carrier, and OCR is about to start assigning it automatically —
+-- picking either row while both exist would keep splitting the book.
+--
+-- "ANA SEGUROS" is the survivor because it is where the 738 already are.
+--
+-- Written as joins rather than subqueries so that BOTH statements are no-ops
+-- when either row is absent (a fresh database, or one where this was already
+-- tidied by hand). A subquery form would resolve to NULL and blank the
+-- carrier off every ANA policy.
+UPDATE `policies` p
+    JOIN `insurance_providers` dup  ON dup.`id` = p.`insuranceProviderId` AND dup.`name` = 'ANA'
+    JOIN `insurance_providers` keep ON keep.`name` = 'ANA SEGUROS'
+    SET p.`insuranceProviderId` = keep.`id`;
+
+DELETE dup FROM `insurance_providers` dup
+    JOIN `insurance_providers` keep ON keep.`name` = 'ANA SEGUROS'
+    WHERE dup.`name` = 'ANA'
+      -- Belt and braces: never drop a row that still has policies hanging off
+      -- it, whatever the UPDATE above did or did not manage to move.
+      AND NOT EXISTS (SELECT 1 FROM `policies` p WHERE p.`insuranceProviderId` = dup.`id`);

packages/database/prisma/migrations/20260815180000_policy_ocr_customer_suggestions/migration.sql

@@ -0,0 +1,7 @@
+-- Ranked customers whose name matches the printed insured name, for the
+-- documents whose policy number found nothing and therefore need a customer
+-- picked by hand. Kept in its own column rather than folded into
+-- `matchCandidates`, which the review screen reads as policy-number hits —
+-- a name is a suggestion and must never be able to masquerade as a match.
+ALTER TABLE `policy_ocr_documents`
+    ADD COLUMN `customerSuggestions` JSON NULL;

packages/database/prisma/migrations/20260818120000_policy_premium_breakdown/migration.sql

@@ -0,0 +1,37 @@
+-- Premium breakdown the Access capture form had and this schema did not:
+-- RECARGO, IVA and PRIMA TOTAL on the policy header, the same six figures per
+-- payment on the installments, and the FORMA PAGO that decides whether a
+-- surcharge applies at all.
+--
+-- IVA and TOTAL were never columns in Access — they were unbound calculated
+-- controls on the form — so there is nothing to backfill for them here and
+-- every migrated row stays null until somebody edits the policy. RECARGO and
+-- the per-installment figures DO exist in the legacy data; they are currently
+-- stranded inside `policies.coveragesJson` (the migration swept every column
+-- it did not model into that blob) and are recovered by
+-- `migration/backfill_policy_premium_breakdown.py`, not by this migration.
+
+ALTER TABLE `policy_types`
+  ADD COLUMN `taxRate` DECIMAL(6, 4) NULL;
+
+ALTER TABLE `policies`
+  ADD COLUMN `surcharge` DECIMAL(12, 2) NULL,
+  ADD COLUMN `tax` DECIMAL(12, 2) NULL,
+  ADD COLUMN `taxRate` DECIMAL(6, 4) NULL,
+  ADD COLUMN `paymentFrequency` ENUM('ANNUAL', 'SEMIANNUAL', 'QUARTERLY', 'MONTHLY', 'SINGLE') NULL;
+
+ALTER TABLE `policy_payment_installments`
+  ADD COLUMN `netPremium` DECIMAL(12, 2) NULL,
+  ADD COLUMN `surcharge` DECIMAL(12, 2) NULL,
+  ADD COLUMN `policyFee` DECIMAL(12, 2) NULL,
+  ADD COLUMN `tax` DECIMAL(12, 2) NULL,
+  ADD COLUMN `taxRate` DECIMAL(6, 4) NULL,
+  ADD COLUMN `total` DECIMAL(12, 2) NULL,
+  ADD COLUMN `commission` DECIMAL(12, 2) NULL;
+
+-- Seed the rate the books actually use. The legacy IMPUESTOS and
+-- IMPUESTOS_AUTOS tables each held exactly one row, both 0.0800, covering the
+-- home and auto lines respectively; applying it to every existing type
+-- reproduces current behaviour rather than changing it. Types created later
+-- start null and fall back to the API default.
+UPDATE `policy_types` SET `taxRate` = 0.0800 WHERE `taxRate` IS NULL;

packages/database/prisma/migrations/20260818140000_policy_ocr_extracted_tax/migration.sql

@@ -0,0 +1,9 @@
+-- A.N.A. prints IVA on the policy face and the parser already read it, but
+-- `ParsedPolicy` had no field for it, so the figure only ever reached a review
+-- note and the confirmed Policy was written with `tax` null. This gives it a
+-- column, matching the premium fields beside it.
+--
+-- GMX stays null: its certificate carries no premium at all, so there is no
+-- tax on it to read either.
+ALTER TABLE `policy_ocr_documents`
+  ADD COLUMN `extractedTax` DECIMAL(12, 2) NULL;

packages/database/prisma/schema.prisma

@@ -158,10 +158,31 @@ model InsuranceProvider {
   @@map("insurance_providers")
 }
 
+/// How the premium is split into payments. Drives whether a surcharge
+/// applies at all: the legacy books only ever charge `recargo` on a policy
+/// paid in more than one exhibición, never on an annual one. Values come from
+/// the Access `FORMA PAGO` column (ANNUAL / SEMESTRAL / CONTADO) plus the
+/// quarterly option Jorge sells today but never recorded in Access.
+enum PaymentFrequency {
+  ANNUAL
+  SEMIANNUAL
+  QUARTERLY
+  MONTHLY
+  /// Legacy "CONTADO" — the whole premium in one payment, no schedule.
+  SINGLE
+}
+
 model PolicyType {
   id               String   @id @default(uuid())
   name             String   @unique
   shortDescription String?
+  /// IVA rate charged on this line of business, as a fraction (0.08 = 8%).
+  /// Replaces the legacy one-row IMPUESTOS / IMPUESTOS_AUTOS tables, which
+  /// held exactly one rate each — per line of business, editable without a
+  /// deploy, because the rate is a tax rule and tax rules change. Null falls
+  /// back to DEFAULT_TAX_RATE in the API rather than to "no tax", so a type
+  /// nobody has configured still computes the same 8% the books use today.
+  taxRate          Decimal? @db.Decimal(6, 4)
   policies         Policy[]
 
   @@map("policy_types")
@@ -185,10 +206,32 @@ model Policy {
   policyTo            DateTime?
   coveragePeriodDays  Int?               @default(365)
   netPremium          Decimal?           @db.Decimal(12, 2)
+  /// "Recargo" — the financing surcharge for paying in installments. Entered
+  /// by hand, never derived: it is quoted by the carrier, not computed here.
+  /// Only ever set when `paymentFrequency` is not ANNUAL/SINGLE, and it IS
+  /// part of the taxable base (verified against the Access books: policy
+  /// 7006785 only reconciles as (610.86 + 8.55 + 31.00) * 0.08 = 52.03).
+  surcharge           Decimal?           @db.Decimal(12, 2)
   policyFee           Decimal?           @db.Decimal(12, 2)
   brokerFee           Decimal?           @db.Decimal(12, 2)
   commission          Decimal?           @db.Decimal(12, 2)
+  /// IVA. Access never stored this — it was an unbound calculated control on
+  /// the form — so every legacy row starts null and is filled going forward.
+  /// Stored rather than computed on read because the printed policy is the
+  /// record of truth and its rounding must survive a later rate change.
+  tax                 Decimal?           @db.Decimal(12, 2)
+  /// The rate actually applied when `tax` was written, as a fraction. Kept on
+  /// the row so a policy issued at 8% still reads back as 8% after somebody
+  /// edits the PolicyType to a new rate.
+  taxRate             Decimal?           @db.Decimal(6, 4)
+  /// Prima total = netPremium + surcharge + policyFee + tax. Populated by the
+  /// capture form from now on. NOTE the legacy rows: `total` is 0 or null on
+  /// all but 2 of 2378 migrated policies, so list/sort code must keep using
+  /// netPremium as the headline (see policies.service.ts).
   total               Decimal?           @db.Decimal(12, 2)
+  /// ANNUAL on all but 31 legacy rows — and the migration used to drop the
+  /// column entirely, so every pre-2026 policy reads null here.
+  paymentFrequency    PaymentFrequency?
   currency            Currency           @default(MXN)
   observations        String?            @db.Text
   notes               String?            @db.Text
@@ -267,6 +310,23 @@ model PolicyPaymentInstallment {
   checkNumber String?
   isCash      Boolean   @default(false)
 
+  // Per-payment premium breakdown. A policy paid in more than one exhibición
+  // prices EACH payment separately — its own net premium, its own surcharge,
+  // its own IVA — which is why the Access form printed the whole money row
+  // twice (P NETA / RECARGO / D POL / IVA / TOTAL / COM, once per pago) and
+  // why these cannot live on the policy header alone. `amount` stays the
+  // authoritative figure actually collected: it is what the cheque was
+  // written for and it drifts from `total` by a peso or two in the books
+  // (policy 7006785: amount 702.73 vs total 702.44), so it is deliberately
+  // NOT recomputed from this breakdown.
+  netPremium Decimal? @db.Decimal(12, 2)
+  surcharge  Decimal? @db.Decimal(12, 2)
+  policyFee  Decimal? @db.Decimal(12, 2)
+  tax        Decimal? @db.Decimal(12, 2)
+  taxRate    Decimal? @db.Decimal(6, 4)
+  total      Decimal? @db.Decimal(12, 2)
+  commission Decimal? @db.Decimal(12, 2)
+
   @@map("policy_payment_installments")
 }
 
@@ -379,8 +439,11 @@ model PolicyDocument {
 /// source PDF and optionally writes a premium Transaction.
 model PolicyOcrBatch {
   id           String               @id @default(uuid())
-  /// Which insurance provider portal the batch came from. "GMX" today;
+  /// Which insurance provider portal the batch came from — "GMX", "ANA", or
-  /// future providers (AXA, GNP, …) extend the parser, not this table.
+  /// "GMX + ANA" when one upload mixed them. Set by the pipeline from what
+  /// the parsers actually claimed, not asked of the uploader, so it can
+  /// never contradict the documents. Future providers extend the parser,
+  /// not this table.
   provider     String               @default("GMX")
   status       PolicyOcrBatchStatus @default(UPLOADED)
   uploadedById String
@@ -427,36 +490,69 @@ model PolicyOcrDocument {
   provider      String?
 
   // Extracted header fields, all staff-editable in review.
-  extractedPolicyNumber      String?
+  extractedPolicyNumber       String?
-  extractedInsuredName       String?
+  extractedInsuredName        String?
-  extractedAdditionalInsured String?
+  extractedAdditionalInsured  String?
-  extractedAgentName         String?
+  extractedAgentName          String?
-  extractedLegalAddress      String?   @db.Text
+  extractedLegalAddress       String?   @db.Text
-  extractedZip               String?
+  extractedZip                String?
-  extractedPolicyFrom        DateTime?
+  extractedPolicyFrom         DateTime?
-  extractedPolicyTo          DateTime?
+  extractedPolicyTo           DateTime?
-  extractedPolicyDate        DateTime?
+  extractedPolicyDate         DateTime?
-  extractedCurrency          String?
+  extractedCurrency           String?
-  extractedNetPremium        Decimal?  @db.Decimal(12, 2)
+  extractedNetPremium         Decimal?  @db.Decimal(12, 2)
-  extractedPolicyFee         Decimal?  @db.Decimal(12, 2)
+  extractedPolicyFee          Decimal?  @db.Decimal(12, 2)
-  extractedBrokerFee         Decimal?  @db.Decimal(12, 2)
+  extractedBrokerFee          Decimal?  @db.Decimal(12, 2)
-  extractedTotal             Decimal?  @db.Decimal(12, 2)
+  /// IVA off A.N.A.'s `TAX` cell. Null on GMX, whose certificate carries no
+  /// premium at all. The adjacent `LOCAL TAX` is a separate levy with no
+  /// column of its own and is NOT summed in — it would make the figure stop
+  /// dividing back to a rate; the parser reports a non-zero one as a note.
+  extractedTax                Decimal?  @db.Decimal(12, 2)
+  extractedTotal              Decimal?  @db.Decimal(12, 2)
   /// Per-coverage rows from the GMX "Material damages" / "Additional risk"
-  /// tables — preserved verbatim so a missing premium receipt still leaves
+  /// tables and ANA's numbered risk sections — preserved verbatim so a
-  /// the coverages auditable.
+  /// missing premium receipt still leaves the coverages auditable.
-  extractedCoveragesJson     Json?
+  extractedCoveragesJson      Json?
-  extractedPremiumPayment    String?
+  extractedPremiumPayment     String?
+  /// Printed term length. ANA sells 3- and 4-day tourist policies, so
+  /// leaving `Policy.coveragePeriodDays` at its 365 default would overstate
+  /// a weekend policy by a year.
+  extractedCoveragePeriodDays Int?
+  /// `ParsedVehicle[]` off ANA's ITEM/YEAR/MAKE/BODY/SERIAL/PLATES table.
+  /// Written to `Vehicle` rows on confirm; kept here so the review screen
+  /// shows what was read before anything is applied.
+  extractedVehiclesJson       Json?
+  /// `ParsedDriver[]` — the insured on ANA's automobile face, the numbered
+  /// POLICY HOLDER list on its driver's policy. Written to `InsuredDriver`
+  /// rows on confirm.
+  extractedDriversJson        Json?
+  /// The `PolicyType.name` the parser read the product as ("AUTO",
+  /// "LICENCIAS", "MULT"). A NAME, not an id — the parser never touches the
+  /// database, so confirm resolves it against `policy_types` and leaves
+  /// `Policy.policyTypeId` null if there is no such row.
+  extractedPolicyTypeName     String?
 
   // Match by `Policy.policyNumber` → existing Policy / Customer.
-  matchedPolicyId   String?
+  matchedPolicyId     String?
-  matchedPolicy     Policy?   @relation("PolicyOcrDocumentPolicy", fields: [matchedPolicyId], references: [id])
+  matchedPolicy       Policy?   @relation("PolicyOcrDocumentPolicy", fields: [matchedPolicyId], references: [id])
-  matchedCustomerId String?
+  matchedCustomerId   String?
-  matchedCustomer   Customer? @relation("PolicyOcrDocumentCustomer", fields: [matchedCustomerId], references: [id])
+  matchedCustomer     Customer? @relation("PolicyOcrDocumentCustomer", fields: [matchedCustomerId], references: [id])
   /// All policies carrying the same number, with their customer. One is
   /// normal; >1 means the policy number is shared across customers and a
   /// human must pick.
-  matchCandidates   Json?
+  matchCandidates     Json?
-  matchNote         String?
+  /// `CustomerNameSuggestion[]` — customers whose name matches the printed
+  /// insured name, ranked. A SUGGESTION, never a match: it is deliberately
+  /// kept out of `matchCandidates` so the review screen cannot mistake a
+  /// name hint for a policy-number hit, and it never sets
+  /// `matchedCustomerId`. Only populated when the policy number found
+  /// nothing, which is exactly when staff have to pick a customer by hand.
+  customerSuggestions Json?
+  /// Text, not VARCHAR(191): this carries the parser's whole note trail, and
+  /// a multi-section ANA policy runs past 191 characters routinely. Silently
+  /// truncating it drops the tail notes, which are the ones that say what
+  /// could NOT be read.
+  matchNote           String?   @db.Text
 
   reviewedById String?
   reviewedBy   User?     @relation("PolicyOcrDocumentReviewer", fields: [reviewedById], references: [id])
@@ -990,8 +1086,8 @@ enum EmailNotificationStatus {
 /// we store it always, so a customer reply quoting an old email can be traced
 /// to the exact letter that was sent.
 model EmailNotificationLog {
-  id                String                   @id @default(uuid())
+  id                String                    @id @default(uuid())
-  sendDate          DateTime                 @default(now())
+  sendDate          DateTime                  @default(now())
   notificationType  EmailNotificationType
   /// Per-type discriminator, null where the type has none:
   ///   ACCOUNT_STATUS → 0 = yellow ("DEBAJO DEL TIPO"), 1 = red ("EN ROJO")
@@ -1009,7 +1105,7 @@ model EmailNotificationLog {
   /// resolve the owner through `Property.customerId`, so this stays set on
   /// job 4 too. Null only on skipped rows where the lookup itself failed.
   customerId        String?
-  customer          Customer?                @relation(fields: [customerId], references: [id])
+  customer          Customer?                 @relation(fields: [customerId], references: [id])
   customerName      String
   customerEmail     String
   /// Subject line of the email we attempted to send.
@@ -1017,16 +1113,16 @@ model EmailNotificationLog {
   /// For PAYMENT_CONFIRMATION: the per-customer URL the PHP code built and
   /// fetched (kept verbatim so the legacy format is reproducible). Null on
   /// the other three jobs — the body is built inline.
-  bodyRequestUrl    String?                  @db.Text
+  bodyRequestUrl    String?                   @db.Text
   /// The HTML body that was sent (or that would have been sent, for SKIPPED
   /// rows). Stored verbatim so audit/customer-service can read the exact
   /// letter that went out without re-running the render.
-  bodySnapshot      String                   @db.Text
+  bodySnapshot      String                    @db.Text
   /// True when `debug` was passed — the recipient was overridden to the
   /// admin address and no real customer received the mail. Kept here so a
   /// "where did all these emails go" investigation finds the answer in one
   /// place instead of "who ran what with what flags" archaeology.
-  debug             Boolean                  @default(false)
+  debug             Boolean                   @default(false)
   /// SES SendEmail MessageId, when we actually got one back. Null on
   /// failures, skipped rows, and dev/mock transport.
   providerMessageId String?
@@ -1034,7 +1130,7 @@ model EmailNotificationLog {
   /// insert so a verbose SES bounce payload can't blow the column.
   providerResponse  String?
   status            EmailNotificationStatus
-  error             String?                  @db.Text
+  error             String?                   @db.Text
 
   @@index([sendDate])
   @@index([notificationType, sendDate])

scripts/corte-audit.mjs

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+/**
+ * Corte (year-end cut) audit — READ ONLY. Writes nothing, voids nothing.
+ *
+ * Legacy Access ran a corte every year: it moved the year's utility movements
+ * into a per-year table and stamped one BALANCE FORWARD row per customer,
+ * dated Jan 1, carrying the closing balance. The platform inherited the ROWS
+ * (1,170 of them, dated 2026-01-01 — legacy's last cut before the extract) but
+ * not the PROCESS, and BillingService uses those rows as a per-customer floor
+ * (BALANCE_FLOOR_JOIN / NOT_SUPERSEDED in apps/api/src/billing/billing.service.ts).
+ *
+ * This script reports the two populations that floor does not cover:
+ *
+ *   A. FLOORLESS customers — no BALANCE FORWARD row at all, so their balance
+ *      is a raw lifetime sum. The platform only migrated the CURRENT-year
+ *      charge ledger (datos2); the per-year charge tables live in DreamHost
+ *      and were never staged. What survives before the cutover is therefore
+ *      the EFECTIVO cash journal — receipts with no matching charges — so
+ *      those sums read as the office owing money it does not owe.
+ *
+ *   B. DOUBLE-BOOKED 2026 RECEIPTS — one cash receipt recorded twice, once in
+ *      EFECTIVO with folio `N` and once in datos2 with reference `CN`. Both
+ *      rows are after the 2026-01-01 floor, so both count. The statement hides
+ *      them (STATEMENT_EXCLUDED_SOURCE_TABLES drops EFECTIVO); the balances
+ *      worklist, the movement browser and the /clientes/:id card do not.
+ *
+ *      The folio alone neither proves nor disproves a pair, so it is used as a
+ *      lead and never as the verdict. Folios are reused, so `C13483` can collide
+ *      with an unrelated receipt; folios are also mistyped, so a genuine pair can
+ *      carry two different numbers. Detection therefore runs twice — once on the
+ *      `CN` cross-reference, once over the C-refs that pass left orphaned, this
+ *      time on proximity alone (same customer, within three days) — and BOTH
+ *      passes are then judged on the money: identical amount when the two legs
+ *      share a currency, or an implied USD->MXN rate inside the band the
+ *      exchange_rates table actually observed that year. Anything that fails is
+ *      reported apart and must not be counted as duplicated money.
+ *
+ *      The second pass is not a refinement. Jorge Jr's own account carries
+ *      `C13647` against EFECTIVO folio `13649` — same day, same 3,500.00 — and
+ *      POWERS carries `C135808` against `13508`. Folio matching alone reports
+ *      both accounts as clean.
+ *
+ *   node scripts/corte-audit.mjs                  # summary + both sections
+ *   node scripts/corte-audit.mjs --cutover 2026-01-01
+ *   node scripts/corte-audit.mjs --csv-a          # per-customer table, section A
+ *   node scripts/corte-audit.mjs --csv-b          # per-pair table, section B
+ *   node scripts/corte-audit.mjs --limit 40       # rows printed per section
+ *
+ * Needs DATABASE_URL. Point it at PROD — a stale copy answers about itself.
+ * On a database imported before the BALANCE FORWARD type was minted those rows
+ * carry typeId NULL instead (see numid.service.ts:80), so the floor is matched
+ * in BOTH shapes here; matching only the type name reports every customer as
+ * floorless on such a copy.
+ */
+import pkg from "../packages/database/generated/client/index.js";
+
+const { PrismaClient } = pkg;
+
+/** Prisma hands raw DECIMAL back as Decimal|string|null; counts as BigInt. */
+const d = (v) => (v == null ? 0 : Number(v));
+const money = (v) => d(v).toFixed(2).padStart(13);
+/**
+ * Raw DATE/DATETIME columns arrive as JS Date objects. String() would render
+ * them in the host's local zone, which turns a row stored at 2026-01-01 00:00
+ * UTC into "Dec 31" on a US Pacific laptop — the ledger is keyed on UTC dates
+ * everywhere else, so format in UTC and nowhere else.
+ */
+const day = (v) => (v == null ? "—" : new Date(v).toISOString().slice(0, 10));
+
+function arg(args, name, fallback = null) {
+  const i = args.indexOf(name);
+  return i === -1 ? fallback : args[i + 1];
+}
+
+/**
+ * A row is a balance-forward marker in either of two shapes. Keep in step with
+ * EMPTY_NUMID_SQL in apps/api/src/customers/numid.service.ts.
+ */
+const BF_PREDICATE = `(
+  tt.nameEn = 'BALANCE FORWARD'
+  OR (t.typeId IS NULL AND MONTH(t.transactionDate) = 1 AND DAY(t.transactionDate) = 1
+      AND t.legacySourceTable = 'datos2')
+)`;
+
+async function main() {
+  const args = process.argv.slice(2);
+  const limit = Number(arg(args, "--limit", "25"));
+  const prisma = new PrismaClient();
+
+  try {
+    // ---- cutover -----------------------------------------------------------
+    // Default to the newest balance-forward date actually in the book rather
+    // than to the current year: the cut the data reflects is a fact, not a
+    // preference, and hardcoding 2026 would silently lie on any other copy.
+    const [bfDates] = await prisma.$queryRawUnsafe(`
+      SELECT MAX(t.transactionDate) AS newest, MIN(t.transactionDate) AS oldest,
+             COUNT(*) AS rows_, COUNT(DISTINCT t.customerId) AS custs
+      FROM transactions t LEFT JOIN type_transactions tt ON tt.id = t.typeId
+      WHERE t.voidedAt IS NULL AND ${BF_PREDICATE}
+    `);
+
+    const cutover =
+      arg(args, "--cutover") ??
+      (bfDates.newest ? new Date(bfDates.newest).toISOString().slice(0, 10) : null);
+
+    if (!cutover) {
+      console.log("No BALANCE FORWARD rows in this database and no --cutover given.");
+      return;
+    }
+
+    console.log(`corte audit — cutover ${cutover}`);
+    console.log(
+      `  balance-forward rows: ${d(bfDates.rows_)} across ${d(bfDates.custs)} customers` +
+        `, dated ${day(bfDates.oldest)}..${day(bfDates.newest)}`,
+    );
+
+    // ---- book totals -------------------------------------------------------
+    const [book] = await prisma.$queryRawUnsafe(
+      `
+      WITH bfloor AS (
+        SELECT t.customerId, MAX(t.transactionDate) AS floorDate
+        FROM transactions t LEFT JOIN type_transactions tt ON tt.id = t.typeId
+        WHERE t.voidedAt IS NULL AND ${BF_PREDICATE}
+        GROUP BY t.customerId
+      )
+      SELECT
+        ROUND(SUM(CASE WHEN t.currency='MXN' THEN t.amount ELSE 0 END), 2) AS rawMxn,
+        ROUND(SUM(CASE WHEN t.currency='USD' THEN t.amount ELSE 0 END), 2) AS rawUsd,
+        ROUND(SUM(CASE WHEN t.currency='MXN' AND (b.floorDate IS NULL OR t.transactionDate >= b.floorDate)
+                       THEN t.amount ELSE 0 END), 2) AS todayMxn,
+        ROUND(SUM(CASE WHEN t.currency='USD' AND (b.floorDate IS NULL OR t.transactionDate >= b.floorDate)
+                       THEN t.amount ELSE 0 END), 2) AS todayUsd,
+        ROUND(SUM(CASE WHEN t.currency='MXN' AND t.transactionDate >= ?
+                       THEN t.amount ELSE 0 END), 2) AS flooredMxn,
+        ROUND(SUM(CASE WHEN t.currency='USD' AND t.transactionDate >= ?
+                       THEN t.amount ELSE 0 END), 2) AS flooredUsd
+      FROM transactions t
+      LEFT JOIN bfloor b ON b.customerId = t.customerId
+      WHERE t.voidedAt IS NULL AND t.outstanding = 0
+      `,
+      cutover,
+      cutover,
+    );
+
+    // ---- section A: floorless customers ------------------------------------
+    const floorless = await prisma.$queryRawUnsafe(
+      `
+      WITH nobf AS (
+        SELECT c.id, c.name
+        FROM customers c
+        WHERE EXISTS (SELECT 1 FROM transactions t WHERE t.customerId = c.id AND t.voidedAt IS NULL)
+          AND NOT EXISTS (
+            SELECT 1 FROM transactions t LEFT JOIN type_transactions tt ON tt.id = t.typeId
+            WHERE t.customerId = c.id AND t.voidedAt IS NULL AND ${BF_PREDICATE}
+          )
+      )
+      SELECT n.id, n.name,
+             COUNT(*)                                                          AS rows_,
+             SUM(t.transactionDate <  ?)                                       AS preRows,
+             SUM(t.transactionDate >= ?)                                       AS postRows,
+             MIN(t.transactionDate)                                            AS firstTx,
+             MAX(t.transactionDate)                                            AS lastTx,
+             SUM(t.domain = 'UTILITY')                                         AS utilRows,
+             SUM(t.domain = 'INSURANCE')                                       AS insRows,
+             ROUND(SUM(CASE WHEN t.currency='MXN' AND t.outstanding=0 THEN t.amount ELSE 0 END), 2) AS todayMxn,
+             ROUND(SUM(CASE WHEN t.currency='USD' AND t.outstanding=0 THEN t.amount ELSE 0 END), 2) AS todayUsd,
+             ROUND(SUM(CASE WHEN t.currency='MXN' AND t.outstanding=0 AND t.transactionDate >= ?
+                            THEN t.amount ELSE 0 END), 2)                       AS afterMxn,
+             ROUND(SUM(CASE WHEN t.currency='USD' AND t.outstanding=0 AND t.transactionDate >= ?
+                            THEN t.amount ELSE 0 END), 2)                       AS afterUsd
+      FROM nobf n
+      JOIN transactions t ON t.customerId = n.id AND t.voidedAt IS NULL
+      GROUP BY n.id, n.name
+      ORDER BY ABS(SUM(CASE WHEN t.currency='MXN' AND t.transactionDate < ? THEN t.amount ELSE 0 END)) DESC
+      `,
+      cutover, cutover, cutover, cutover, cutover,
+    );
+
+    // Direction of the pre-cutover history, which is the whole argument for
+    // flooring rather than carrying it: a corte carries a NET, and a net built
+    // from receipts whose charges were never migrated is not one.
+    const [split] = await prisma.$queryRawUnsafe(
+      `
+      WITH nobf AS (
+        SELECT c.id FROM customers c
+        WHERE EXISTS (SELECT 1 FROM transactions t WHERE t.customerId = c.id AND t.voidedAt IS NULL)
+          AND NOT EXISTS (
+            SELECT 1 FROM transactions t LEFT JOIN type_transactions tt ON tt.id = t.typeId
+            WHERE t.customerId = c.id AND t.voidedAt IS NULL AND ${BF_PREDICATE}
+          )
+      )
+      SELECT SUM(t.amount < 0) AS charges, ROUND(SUM(CASE WHEN t.amount < 0 THEN t.amount ELSE 0 END), 2) AS chargeMxn,
+             SUM(t.amount > 0) AS credits, ROUND(SUM(CASE WHEN t.amount > 0 THEN t.amount ELSE 0 END), 2) AS creditMxn
+      FROM transactions t JOIN nobf n ON n.id = t.customerId
+      WHERE t.voidedAt IS NULL AND t.transactionDate < ?
+      `,
+      cutover,
+    );
+
+    // ---- section B: double-booked receipts ---------------------------------
+    const pairs = await prisma.$queryRawUnsafe(
+      `
+      SELECT d.id AS datos2Id, e.id AS efectivoId, c.name,
+             DATE(d.transactionDate) AS datos2Date, DATE(e.transactionDate) AS efectivoDate,
+             d.amount AS datos2Amount, d.currency AS datos2Currency,
+             e.amount AS efectivoAmount, e.currency AS efectivoCurrency,
+             d.reference AS datos2Ref, e.reference AS efectivoRef,
+             fx.lo AS rateLo, fx.hi AS rateHi
+      FROM transactions d
+      JOIN transactions e
+        ON e.customerId = d.customerId
+       AND e.legacySourceTable = 'EFECTIVO'
+       AND e.voidedAt IS NULL
+       AND e.reference = SUBSTRING(d.reference, 2)
+      JOIN customers c ON c.id = d.customerId
+      LEFT JOIN (
+        SELECT YEAR(effectiveDate) AS y, MIN(rate) AS lo, MAX(rate) AS hi
+        FROM exchange_rates GROUP BY YEAR(effectiveDate)
+      ) fx ON fx.y = YEAR(d.transactionDate)
+      WHERE d.voidedAt IS NULL
+        AND d.legacySourceTable = 'datos2'
+        AND d.reference REGEXP '^C[0-9]+$'
+      ORDER BY d.transactionDate
+      `,
+    );
+
+    // Pass two — the leads pass one could not follow. Same shape of row, judged
+    // by the same money rules below, so a folio typo costs nothing.
+    const nearby = await prisma.$queryRawUnsafe(
+      `
+      SELECT d.id AS datos2Id, e.id AS efectivoId, c.name,
+             DATE(d.transactionDate) AS datos2Date, DATE(e.transactionDate) AS efectivoDate,
+             d.amount AS datos2Amount, d.currency AS datos2Currency,
+             e.amount AS efectivoAmount, e.currency AS efectivoCurrency,
+             d.reference AS datos2Ref, e.reference AS efectivoRef,
+             fx.lo AS rateLo, fx.hi AS rateHi
+      FROM transactions d
+      JOIN transactions e
+        ON e.customerId = d.customerId AND e.legacySourceTable = 'EFECTIVO'
+       AND e.voidedAt IS NULL AND e.amount > 0
+       AND ABS(DATEDIFF(e.transactionDate, d.transactionDate)) <= 3
+      JOIN customers c ON c.id = d.customerId
+      LEFT JOIN (
+        SELECT YEAR(effectiveDate) AS y, MIN(rate) AS lo, MAX(rate) AS hi
+        FROM exchange_rates GROUP BY YEAR(effectiveDate)
+      ) fx ON fx.y = YEAR(d.transactionDate)
+      WHERE d.voidedAt IS NULL AND d.legacySourceTable = 'datos2'
+        AND d.reference REGEXP '^C[0-9]+$'
+        AND NOT EXISTS (
+          SELECT 1 FROM transactions x
+          WHERE x.customerId = d.customerId AND x.legacySourceTable = 'EFECTIVO'
+            AND x.voidedAt IS NULL AND x.reference = SUBSTRING(d.reference, 2)
+        )
+      ORDER BY d.transactionDate
+      `,
+    );
+
+    const [unpaired] = await prisma.$queryRawUnsafe(
+      `
+      SELECT COUNT(*) AS n
+      FROM transactions d
+      WHERE d.voidedAt IS NULL AND d.legacySourceTable = 'datos2'
+        AND d.reference REGEXP '^C[0-9]+$'
+        AND NOT EXISTS (
+          SELECT 1 FROM transactions e
+          WHERE e.customerId = d.customerId AND e.legacySourceTable = 'EFECTIVO'
+            AND e.voidedAt IS NULL AND e.reference = SUBSTRING(d.reference, 2)
+        )
+      `,
+    );
+
+    // ---- CSV escapes -------------------------------------------------------
+    if (args.includes("--csv-a")) return dumpCsv(floorless);
+    if (args.includes("--csv-b")) return dumpCsv([...pairs, ...nearby]);
+
+    // ---- report ------------------------------------------------------------
+    console.log("\nBOOK (voided and outstanding rows excluded)");
+    console.log(`  raw lifetime sum, no floor       ${money(book.rawMxn)} MXN  ${money(book.rawUsd)} USD`);
+    console.log(`  today (per-customer BF floor)    ${money(book.todayMxn)} MXN  ${money(book.todayUsd)} USD`);
+    console.log(`  flat floor at ${cutover}       ${money(book.flooredMxn)} MXN  ${money(book.flooredUsd)} USD`);
+
+    const preRowsTotal = floorless.reduce((s, r) => s + d(r.preRows), 0);
+    const wouldZero = floorless.filter((r) => d(r.postRows) === 0);
+    const deltaMxn = floorless.reduce((s, r) => s + (d(r.todayMxn) - d(r.afterMxn)), 0);
+    const deltaUsd = floorless.reduce((s, r) => s + (d(r.todayUsd) - d(r.afterUsd)), 0);
+
+    console.log(`\nA. FLOORLESS CUSTOMERS — ${floorless.length}`);
+    console.log(`   pre-cutover rows they still count: ${preRowsTotal}`);
+    console.log(`   of those rows: ${d(split.charges)} charges (${d(split.chargeMxn).toFixed(2)})` +
+                ` vs ${d(split.credits)} credits (${d(split.creditMxn).toFixed(2)})`);
+    console.log(`   balance moved by flooring:        ${money(-deltaMxn)} MXN  ${money(-deltaUsd)} USD`);
+    console.log(`   customers left with NO rows at all after the cut: ${wouldZero.length}` +
+                ` (their balance becomes 0 — an assertion, not a migrated figure)`);
+    console.log(
+      `\n   ${"customer".padEnd(30)} ${"pre".padStart(4)} ${"post".padStart(4)}` +
+        ` ${"today MXN".padStart(13)} ${"after MXN".padStart(13)} ${"first tx".padStart(10)}`,
+    );
+    for (const r of floorless.slice(0, limit)) {
+      console.log(
+        `   ${(r.name || "(sin nombre)").slice(0, 30).padEnd(30)}` +
+          ` ${String(d(r.preRows)).padStart(4)} ${String(d(r.postRows)).padStart(4)}` +
+          ` ${money(r.todayMxn)} ${money(r.afterMxn)} ${day(r.firstTx).padStart(10)}`,
+      );
+    }
+    if (floorless.length > limit) console.log(`   ... ${floorless.length - limit} more (--csv-a)`);
+
+    // A folio match is a hypothesis; the money is the evidence. The band is
+    // widened by 10% either side of what exchange_rates observed that year,
+    // because the office keys receipts at its own counter rate, not at a
+    // published one, and a pair should not be called false over a few centavos.
+    const classify = (p) => {
+      const dAmt = d(p.datos2Amount);
+      const eAmt = d(p.efectivoAmount);
+      if (p.datos2Currency === p.efectivoCurrency) {
+        return Math.abs(dAmt - eAmt) < 0.005 ? "confirmed" : "suspect";
+      }
+      if (p.efectivoCurrency !== "USD" || p.datos2Currency !== "MXN") return "suspect";
+      if (!eAmt || !p.rateLo) return "suspect";
+      const implied = dAmt / eAmt;
+      return implied >= d(p.rateLo) * 0.9 && implied <= d(p.rateHi) * 1.1
+        ? "confirmed"
+        : "suspect";
+    };
+    for (const p of pairs) {
+      p.pass = "folio";
+      p.verdict = classify(p);
+    }
+    for (const p of nearby) {
+      p.pass = "proximity";
+      p.verdict = classify(p);
+    }
+    pairs.push(...nearby);
+
+    const confirmed = pairs.filter((p) => p.verdict === "confirmed");
+    const suspect = pairs.filter((p) => p.verdict === "suspect");
+    const byCust = new Set(confirmed.map((p) => p.name));
+    const sameCur = confirmed.filter((p) => p.datos2Currency === p.efectivoCurrency);
+    const converted = confirmed.filter((p) => p.efectivoCurrency === "USD" && p.datos2Currency === "MXN");
+    const efecMxn = confirmed.reduce((s, p) => s + (p.efectivoCurrency === "MXN" ? d(p.efectivoAmount) : 0), 0);
+    const efecUsd = confirmed.reduce((s, p) => s + (p.efectivoCurrency === "USD" ? d(p.efectivoAmount) : 0), 0);
+
+    console.log(`\nB. DOUBLE-BOOKED RECEIPTS — ${confirmed.length} confirmed pairs across ${byCust.size} customers`);
+    const byFolio = confirmed.filter((p) => p.pass === "folio").length;
+    console.log(`   candidates examined: ${pairs.length}  (confirmed ${confirmed.length}, rejected on money ${suspect.length})`);
+    console.log(`   found by folio cross-reference: ${byFolio}, by proximity after a folio miss: ${confirmed.length - byFolio}`);
+    console.log(`   confirmed same-currency, amount equal to the cent: ${sameCur.length}`);
+    console.log(`   confirmed USD receipt posted to datos2 in MXN:     ${converted.length}`);
+    console.log(`   datos2 C-refs with no EFECTIVO partner at all:     ${d(unpaired.n)}`);
+    console.log(`   EFECTIVO side of the confirmed pairs: ${money(efecMxn)} MXN  ${money(efecUsd)} USD`);
+    console.log(
+      `\n   ${"customer".padEnd(28)} ${"datos2".padStart(10)} ${"efectivo".padStart(10)}` +
+        ` ${"datos2 amt".padStart(13)} ${"efectivo amt".padStart(13)}  ref`,
+    );
+    for (const p of confirmed.slice(0, limit)) {
+      console.log(
+        `   ${(p.name || "(sin nombre)").slice(0, 28).padEnd(28)}` +
+          ` ${day(p.datos2Date).padStart(10)} ${day(p.efectivoDate).padStart(10)}` +
+          ` ${money(p.datos2Amount)} ${p.datos2Currency}` +
+          ` ${money(p.efectivoAmount)} ${p.efectivoCurrency}  ${p.datos2Ref}/${p.efectivoRef}`,
+      );
+    }
+    if (confirmed.length > limit) console.log(`   ... ${confirmed.length - limit} more (--csv-b)`);
+
+    if (suspect.length) {
+      console.log(`\n   REJECTED — folio matched, money did not. Not duplicates on this evidence:`);
+      for (const p of suspect.slice(0, limit)) {
+        const implied =
+          d(p.efectivoAmount) && p.datos2Currency !== p.efectivoCurrency
+            ? ` implied ${(d(p.datos2Amount) / d(p.efectivoAmount)).toFixed(2)}`
+            : "";
+        console.log(
+          `   ${(p.name || "(sin nombre)").slice(0, 28).padEnd(28)}` +
+            ` ${day(p.datos2Date).padStart(10)} ${day(p.efectivoDate).padStart(10)}` +
+            ` ${money(p.datos2Amount)} ${p.datos2Currency}` +
+            ` ${money(p.efectivoAmount)} ${p.efectivoCurrency}  ${p.datos2Ref}${implied}`,
+        );
+      }
+      if (suspect.length > limit) console.log(`   ... ${suspect.length - limit} more (--csv-b)`);
+    }
+
+    console.log(
+      "\nNOTE: nothing above has been changed. Section A is a proposal to move the\n" +
+        "floor, not a carried-forward balance: the pre-cutover charge ledger was\n" +
+        "never migrated, so no true opening balance can be computed from this\n" +
+        "database. It exists in the DreamHost per-year tables. Section B is an\n" +
+        "independent defect and does not need a corte to fix.",
+    );
+  } finally {
+    await prisma.$disconnect();
+  }
+}
+
+function dumpCsv(rows) {
+  if (!rows.length) return;
+  const cols = Object.keys(rows[0]);
+  console.log(cols.join(","));
+  for (const r of rows) {
+    console.log(cols.map((c) => JSON.stringify(r[c] == null ? "" : String(r[c]))).join(","));
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

scripts/numid-audit.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * NUMid recycle audit.
+ *
+ * Prints which portal NUMids (customer_legacy_refs, utilities/DATGRAL) are dead
+ * enough to hand to a new customer, and which are merely quiet. Read-only: it
+ * writes nothing and reassigns nothing.
+ *
+ *   node scripts/numid-audit.mjs            # summary + both candidate tiers
+ *   node scripts/numid-audit.mjs --csv      # full per-NUMid table on stdout
+ *   node scripts/numid-audit.mjs --numid 501
+ *
+ * Needs DATABASE_URL. Run it against PROD before acting on anything: the tiers
+ * describe whatever database it is pointed at, and a stale copy will happily
+ * report a NUMid as empty that prod has been billing all year.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Relative, not "@jorgecuadros/database": the workspace link is not always
+// present at the repo root, and this script has to run from a bare checkout and
+// from inside the API container alike.
+import pkg from "../packages/database/generated/client/index.js";
+
+const { PrismaClient } = pkg;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Anything here means the id carries history a new owner would inherit.
+ * Counted, not sampled: a single row in any of them disqualifies.
+ */
+const HISTORY_COLUMNS = [
+  "veh",
+  "trust",
+  "stmt",
+  "ocr",
+  "enl",
+  "elog",
+  "ash",
+  "nopago",
+];
+
+const n = (v) => (v == null ? 0 : Number(v));
+const hasHistory = (r) => HISTORY_COLUMNS.some((c) => n(r[c]) > 0);
+const zeroBalance = (r) => n(r.balMxn) === 0 && n(r.balUsd) === 0;
+
+/**
+ * EMPTY — the id was created and never used. Safe for an allocator to take
+ * without a human looking, subject to the legacy check below.
+ *
+ * "Never transacted" means zero movements once the synthetic opening-balance row
+ * is removed; that row exists for all 1,171 NUMids and is not evidence of use.
+ * Services are checked as anySvc rather than activeSvc, because a deactivated
+ * water account still says a person once lived behind this id.
+ */
+const isEmpty = (r) =>
+  n(r.realTx) === 0 &&
+  zeroBalance(r) &&
+  n(r.anySvc) === 0 &&
+  n(r.anyPol) === 0 &&
+  n(r.insRef) === 0 &&
+  n(r.hasEmail) === 0 &&
+  !hasHistory(r);
+
+/**
+ * DORMANT — used once, quiet for years, owes nothing. NOT auto-allocatable:
+ * a returning snowbird is indistinguishable from an abandoned account here.
+ */
+const isDormant = (r) =>
+  !isEmpty(r) &&
+  n(r.realTx36m) === 0 &&
+  zeroBalance(r) &&
+  n(r.activeSvc) === 0 &&
+  n(r.activePol) === 0 &&
+  !hasHistory(r);
+
+function line(r) {
+  return (
+    `  ${String(r.numid).padStart(5)}  ${(r.name || "(sin nombre)").slice(0, 30).padEnd(30)}` +
+    ` last=${(r.lastRealTx ? new Date(r.lastRealTx).toISOString().slice(0, 10) : "never").padStart(10)}` +
+    ` tx=${String(n(r.realTx)).padStart(3)}` +
+    ` bal=${n(r.balMxn).toFixed(2).padStart(10)}` +
+    ` svc=${n(r.anySvc)}` +
+    ` pol=${n(r.anyPol)}`
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const prisma = new PrismaClient();
+  try {
+    const sql = readFileSync(join(HERE, "numid-audit.sql"), "utf8");
+    const rows = await prisma.$queryRawUnsafe(sql);
+
+    const one = args.indexOf("--numid");
+    if (one !== -1) {
+      const want = Number(args[one + 1]);
+      const r = rows.find((x) => Number(x.numid) === want);
+      if (!r) {
+        console.log(`NUMid ${want} is not in the utilities/DATGRAL pool.`);
+        return;
+      }
+      console.log(JSON.stringify(r, (_k, v) => (typeof v === "bigint" ? Number(v) : v), 2));
+      console.log(
+        `\nverdict: ${isEmpty(r) ? "EMPTY" : isDormant(r) ? "DORMANT" : "IN USE"}`,
+      );
+      return;
+    }
+
+    if (args.includes("--csv")) {
+      const cols = Object.keys(rows[0]);
+      console.log(cols.join(","));
+      for (const r of rows) {
+        console.log(cols.map((c) => JSON.stringify(r[c] ?? "")).join(","));
+      }
+      return;
+    }
+
+    const empty = rows.filter(isEmpty);
+    const dormant = rows.filter(isDormant);
+    const max = rows.reduce((m, r) => Math.max(m, Number(r.numid)), 0);
+
+    console.log(`pool: ${rows.length} NUMids, max ${max}`);
+    console.log(`  EMPTY   (never used, auto-allocatable): ${empty.length}`);
+    console.log(`  DORMANT (quiet, needs a human):         ${dormant.length}`);
+    console.log(`  IN USE:                                 ${rows.length - empty.length - dormant.length}`);
+
+    console.log("\nEMPTY");
+    empty.forEach((r) => console.log(line(r)));
+    console.log("\nDORMANT");
+    dormant.forEach((r) => console.log(line(r)));
+
+    console.log(
+      "\nNOTE: this audit sees the platform only. Every NUMid here also exists in\n" +
+        "Access, and freakma republishes DATGRAL in full on each export, so an id\n" +
+        "reassigned here comes back under its old owner unless it is removed at the\n" +
+        "source or the NUMid is routed to the platform. Confirm against prod\n" +
+        "datosfreak before reassigning.",
+    );
+  } finally {
+    await prisma.$disconnect();
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

scripts/numid-audit.sql

@@ -0,0 +1,104 @@
+-- One row per portal NUMid, with every signal that says whether the id is in use.
+-- Consumed by scripts/numid-audit.mjs, which applies the tier rules.
+--
+-- POOL. customer_legacy_refs where sourceSystem='utilities' AND sourceTable='DATGRAL'.
+-- That pair IS the portal "Security Number" the login screen asks for.
+-- insurance/DATGRAL is a DIFFERENT id space running to 4000 and sharing the same
+-- sourceTable name; drawing from it would hand out an id the portal cannot resolve.
+--
+-- WHY THE OBVIOUS RULES FIND NOTHING.
+--   "every owned row count is zero"      -> 0 of 1,171. Migration gave every NUMid
+--                                           at least one property and one transaction.
+--   "no transaction in the last N years" -> 0 of 1,171. Every customer carries a
+--                                           synthetic Jan-1 opening-balance row, so
+--                                           everyone looks active in the current year.
+-- The opening-balance row has to be subtracted before any of this means anything,
+-- which is what `bf` below does and why `real_tx` exists.
+--
+-- BALANCE-FORWARD DETECTION IS TWO-SHAPED ON PURPOSE.
+-- transform_transactions.py:120 mints a transaction type literally named
+-- 'BALANCE FORWARD'. Databases loaded before that change carry the same rows with
+-- typeId NULL, dated Jan 1, legacySourceTable='datos2' -- 1,170 of them, exactly one
+-- per customer. Matching the type name alone floors nothing on such a database, and
+-- every balance below silently becomes a raw lifetime sum: the same double-count that
+-- read the whole book as +20.6M MXN in credit before d173c9e. Match both shapes.
+--
+-- Balances otherwise follow BillingService exactly -- voided out, outstanding out,
+-- superseded rows out (BALANCE_FLOOR_JOIN / NOT_SUPERSEDED, billing.service.ts:179-210).
+
+WITH bf AS (
+  SELECT t.id, t.customerId, t.transactionDate
+  FROM transactions t
+  LEFT JOIN type_transactions tt ON tt.id = t.typeId
+  WHERE t.voidedAt IS NULL
+    AND (
+      tt.nameEn = 'BALANCE FORWARD'
+      OR (t.typeId IS NULL AND MONTH(t.transactionDate) = 1 AND DAY(t.transactionDate) = 1
+          AND t.legacySourceTable = 'datos2')
+    )
+),
+bfloor AS (
+  SELECT customerId, MAX(transactionDate) AS floorDate FROM bf GROUP BY customerId
+),
+real_tx AS (
+  SELECT t.* FROM transactions t
+  WHERE t.voidedAt IS NULL AND t.id NOT IN (SELECT id FROM bf)
+),
+pool AS (
+  SELECT CAST(r.legacyId AS UNSIGNED) AS numid,
+         c.id AS cid,
+         REPLACE(REPLACE(COALESCE(c.name,''),'\n',' '),'\t',' ') AS name,
+         IF(c.archivedAt IS NULL,0,1) AS archived,
+         IF(c.email IS NULL OR c.email='',0,1) AS hasEmail
+  FROM customer_legacy_refs r
+  JOIN customers c ON c.id = r.customerId
+  WHERE r.sourceSystem='utilities' AND r.sourceTable='DATGRAL'
+)
+SELECT
+  p.numid, p.cid AS customerUuid, p.name, p.archived, p.hasEmail,
+  -- EXISTS, not a join: 16 customers hold more than one insurance ref (several
+  -- insurance rows folded into one customer), and joining them fans this result
+  -- out past one row per NUMid — 1,188 rows for a 1,171-id pool.
+  EXISTS(SELECT 1 FROM customer_legacy_refs i
+         WHERE i.customerId=p.cid AND i.sourceSystem='insurance') AS insRef,
+
+  COALESCE((SELECT ROUND(SUM(t.amount),2) FROM transactions t
+            LEFT JOIN bfloor f ON f.customerId=t.customerId
+            WHERE t.customerId=p.cid AND t.voidedAt IS NULL AND t.outstanding=0
+              AND t.currency='MXN'
+              AND (f.floorDate IS NULL OR t.transactionDate>=f.floorDate)),0) AS balMxn,
+  COALESCE((SELECT ROUND(SUM(t.amount),2) FROM transactions t
+            LEFT JOIN bfloor f ON f.customerId=t.customerId
+            WHERE t.customerId=p.cid AND t.voidedAt IS NULL AND t.outstanding=0
+              AND t.currency='USD'
+              AND (f.floorDate IS NULL OR t.transactionDate>=f.floorDate)),0) AS balUsd,
+
+  (SELECT COUNT(*) FROM transactions t
+     WHERE t.customerId=p.cid AND t.voidedAt IS NULL AND t.outstanding=1) AS nopago,
+  (SELECT COUNT(*) FROM real_tx t WHERE t.customerId=p.cid) AS realTx,
+  (SELECT COUNT(*) FROM real_tx t WHERE t.customerId=p.cid
+     AND t.transactionDate >= DATE_SUB(CURDATE(), INTERVAL 12 MONTH)) AS realTx12m,
+  (SELECT COUNT(*) FROM real_tx t WHERE t.customerId=p.cid
+     AND t.transactionDate >= DATE_SUB(CURDATE(), INTERVAL 36 MONTH)) AS realTx36m,
+  (SELECT DATE(MAX(t.transactionDate)) FROM real_tx t WHERE t.customerId=p.cid) AS lastRealTx,
+
+  (SELECT COUNT(*) FROM properties pr WHERE pr.customerId=p.cid AND pr.archivedAt IS NULL) AS props,
+  -- services are counted BOTH ways: an inactive service is still a record of the id
+  -- having been used, so the auto tier requires zero of any kind.
+  (SELECT COUNT(*) FROM property_services ps JOIN properties pr ON pr.id=ps.propertyId
+     WHERE pr.customerId=p.cid AND pr.archivedAt IS NULL) AS anySvc,
+  (SELECT COUNT(*) FROM property_services ps JOIN properties pr ON pr.id=ps.propertyId
+     WHERE pr.customerId=p.cid AND pr.archivedAt IS NULL AND ps.active=1) AS activeSvc,
+  (SELECT COUNT(*) FROM policies po WHERE po.customerId=p.cid AND po.archivedAt IS NULL
+     AND (po.policyTo IS NULL OR po.policyTo >= CURDATE())) AS activePol,
+  (SELECT COUNT(*) FROM policies po WHERE po.customerId=p.cid AND po.archivedAt IS NULL) AS anyPol,
+  (SELECT COUNT(*) FROM vehicles v WHERE v.customerId=p.cid) AS veh,
+  (SELECT COUNT(*) FROM trust_accounts ta JOIN properties pr ON pr.id=ta.propertyId
+     WHERE pr.customerId=p.cid) AS trust,
+  (SELECT COUNT(*) FROM statement_documents s WHERE s.matchedCustomerId=p.cid) AS stmt,
+  (SELECT COUNT(*) FROM policy_ocr_documents o WHERE o.matchedCustomerId=p.cid) AS ocr,
+  (SELECT COUNT(*) FROM email_notification_log e WHERE e.customerId=p.cid) AS enl,
+  (SELECT COUNT(*) FROM email_log e WHERE e.customerId=p.cid) AS elog,
+  (SELECT COUNT(*) FROM account_status_history a WHERE a.customerId=p.cid) AS ash
+FROM pool p
+ORDER BY p.numid;