[m-murphy]

Summary

Stacked on #89. First slice of ADR 0010: Specimen registration goes behind one module, and validation becomes the write itself, rolled back.

 POST /imports/bulk-combined/validate
-  validateBulkCombinedPayload          # its own checks
-    prepareCombinedSubjectContainerBatch
-    lookupWriteInputCollectionId       # barcode miss → null, no occupancy check
-    collectContainerPlacementErrors    # rejects 2 papers per Sheet
+  withRolledBackTransaction
+    registerSubjects                   # same code as the import

 POST /imports/bulk-combined
-  prepareSubjectWithSpecimens
-  revalidatePreparedSubjectInTx
-  createContainerForSpecimen
-    lookupGridCollectionId             # barcode miss → falls back to name
+  withWriteTransaction
+    registerSubjects                   # find or create Subjects
+      registerSpecimens                # plan all → refuse with every error, or write

lib/specimen-registration/
├── index.ts        # registerSpecimens, checkSpecimenRegistration
├── plan.ts         # Specimen reuse, units, positions, barcodes, sublabels; reads only
├── collections.ts  # every identifier given must name the same Collection
└── write.ts        # inserts; a constraint hit becomes a 409

Rules now enforced in one place:

• Specimen reuse: a Specimen is reused by (Source, type, date).
• Collection identity: a row's name, barcode and id must agree on one Collection. A Collection is created only when nothing matches and a location is given.
• Paper on Sheets: several papers can share a Sheet, but a sublabel can't repeat on one Sheet.
• Grid position clashes: checked per resolved Collection, so naming one plate by name and by barcode is caught.

createContainerForSpecimen now wraps registerSpecimens, so derivations, control batches, POST /specimens and add-container already write with these rules. Their separate validators are replaced in slices 2–4.

Evidence

All three mismatches were reproduced against the old code before this change.

• Before: existing plate P1 (barcode P1-BC, tube at A01) and a row { name: 'P1', barcode: 'UNKNOWN', position: 'A01' } → validate { valid: true }, import fails "Position A01 is already used". At A02 the import put the tube in P1.
  After: both report Micronix plate 'P1' has barcode 'P1-BC', not 'UNKNOWN'.
• Before: two subjects with papers on Sheet-1 in one box → validate rejects "Sheet name 'Sheet-1' in box is used more than once", import writes both papers on one sheet.
  After: both accept; a repeated sublabel on that sheet is rejected by both.
• New fixture test, 8 payloads: validate(payload).valid === importSucceeds(payload), and each matches its expected validity.
• 18 module tests. bun run ci:verify passes locally (API: 1069 pass, 0 fail).

Merge Danger

Door: two-way

No schema or wire-shape change. The validate and import response bodies keep their shapes. A full_file import failure now also carries details.errors with every problem.

Blast Radius: every container write

Every path that creates a Container goes through the new module. Inputs that used to pass now fail:

• Contradictory identifiers: a collection name and barcode that point at different plates, or a barcode that misses while the name matches.
• Repeated sublabel: the same sublabel twice on one Sheet.
• Ambiguous new plate: one new plate given two different locations in one request.

Messages for some failures changed wording. Each failure now returns every error in one response.

🤖 Generated with Claude Code