[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).

Review follow-ups

• Validate matches import in per_subject mode too: validate takes the payload's atomicMode and runs each subject in its own savepoint inside the rolled-back transaction, so a subject that depends on a collection a failed subject would have created is flagged by both. The parity fixtures cover both modes.
• 409s: a constraint hit during any container write (add-container, POST /specimens, /specimens/bulk, derivations, control batches) returns 409 with every error, not 400 or 500.
• /specimens/bulk validates and registers through Specimen registration, so its validate and import agree.
• Transactions: each request gets its own transaction on the shared connection; withRolledBackTransaction and the lock are documented in the db README.
• Collection identity: a location that contradicts the collection's own is rejected, and the message names the identifier that found a plate with another name.
• ADRs: ADR 0010 says it amends ADR 0006 and states that collection identifiers must now agree. Its per_subject wording matches the code.
• Cleanup: container types map to collections and tables in one place; typed claim keys and Specimen identity replace strings and -1 sentinels; errors are worded for any caller; the paper barcode check is left to the contract schema; new test factories for allowed container types and units.
• Evidence: bun run ci:verify passes: API 1144, web 948, contract 86.

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.
• Stale identifiers: before, an id won and a name or barcode beside it was ignored. A form that sends an id with a stale name or barcode is now refused with 400.

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

🤖 Generated with Claude Code