From e6de538aa7ce56ea24c46b3ec01b3bf0b0e96162 Mon Sep 17 00:00:00 2001 From: jakeross Date: Wed, 19 Aug 2026 08:59:42 -0700 Subject: [PATCH] docs: record the San Acacia piezometer identifier conflicts Found while reconciling Diver-HUB points against Ocotillo wells. Present in production, not only staging. Three separate problems. The NMBGMR and unattributed identifier sources assign A and B to opposite wells for the BRN-E04 shallow/deep pair. They disagree about whether SO-0262/SO-0263 belong to NRCS site 3 or site 2, where site 2 already exists as SO-0274 and its piezometers. And the A/B suffix does not consistently indicate depth -- A is the deep well at four sites and the shallow one at two, inconsistently even within the NRCS series. None of it blocks ingestion, which matches on SO-#### where both systems agree. It matters to anyone identifying these wells by field name, and a swap on a paired piezometer nest attributes a shallow series to a deep well. Co-Authored-By: Claude Opus 5 --- ...-acacia-piezometer-identifier-conflicts.md | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/san-acacia-piezometer-identifier-conflicts.md diff --git a/docs/san-acacia-piezometer-identifier-conflicts.md b/docs/san-acacia-piezometer-identifier-conflicts.md new file mode 100644 index 000000000..29287abd7 --- /dev/null +++ b/docs/san-acacia-piezometer-identifier-conflicts.md @@ -0,0 +1,77 @@ +# San Acacia piezometer identifier conflicts + +Found 2026-08-19 while reconciling Diver-HUB monitoring points against Ocotillo +wells for the automated ingestion pipeline. Present in **production**, not only +staging. + +None of this blocks ingestion — the vendor names its points `SO-####` and +Ocotillo agrees on those, so matching is exact. It matters to anyone who +identifies these wells by their field names instead. + +## 1. Two identifier sources disagree about which well is which + +`thing_id_link` holds a `NMBGMR` identifier and an unattributed `Unknown` one +for most `SO-` wells. For the BRN-E04 pair they contradict each other: + +| Well | NMBGMR | Unknown | +|---|---|---| +| `SO-0131` | `BRN-E04B (shallow)` | `BRN-E04A` | +| `SO-0132` | `BRN-E04A (deep)` | `BRN-E04B` | + +The two sources assign A and B to opposite wells. Since these are a paired +shallow/deep piezometer nest, resolving `BRN-E04A` to the wrong one attributes a +shallow water-level series to a deep well or the reverse. + +`SO-0131` is one of the 38 points the ingestion pipeline reads. + +## 2. A site number disagreement, which may collide with a real site + +| Well | NMBGMR | Unknown | +|---|---|---| +| `SO-0262` | `NRCS 3A (Deep)` | `NRCS 2 (Deep)` | +| `SO-0263` | `NRCS 3B (Shallow monitor well)` | `NRCS 2 (Shallow)` | + +NRCS site 2 exists separately — `SO-0274` is `NRCS Site 2 Well 2`, and +`SO-0275`/`SO-0276` are its piezometers `2A`/`2B`. So the `Unknown` labels on +`SO-0262`/`SO-0263` either duplicate a different site's number or the `NMBGMR` +labels are wrong. One of the two is. + +## 3. The A/B suffix does not consistently mean depth + +Where NMBGMR annotates depth, the convention reverses between sites: + +| Site | A | B | +|---|---|---| +| `BRN-E04` | deep | shallow | +| `HWY-W09` | deep | shallow | +| `SBB-W02` | deep | shallow | +| `NRCS 3` | deep | shallow | +| `NRCS 4` | **shallow** | **deep** | +| `NRCS 6` | **shallow** | **deep** | + +It is not even consistent within the NRCS series: site 3 has A as the deep well, +sites 4 and 6 have A as the shallow one. + +So the suffix cannot be used to infer completion depth, and any code or analysis +that assumes "A is the deep one" is right for four sites and wrong for two. + +## Why it was not caught earlier + +Nothing reads these identifiers programmatically today. The reconciler found it +because matching on `alternate_id` produced a *confident* match for `BRN-E04A` — +a single hit on `SO-0131`, contradicting NMBGMR, with no ambiguity flag, because +the `(shallow)` suffix makes the two strings differ. + +External-id matching is now opt-in for that reason +(`automated_ingestion/sources/san_acacia/reconcile.py`), with a test pinning +these rows. That is a guard, not a fix: the underlying records still disagree. + +## What resolving it needs + +Someone with the field records or the drilling logs, deciding per pair which +physical well is which. The depth annotations in the NMBGMR labels are the only +in-database evidence, and for BRN-E04 they are exactly what is in dispute. + +Worth checking whether the `Unknown` organization rows have a determinable +provenance — 4,825 links carry it, and if they came from a single import their +reliability can be assessed as a group rather than well by well.