Serial-number create (POST /serial_numbers) semantics appear stale: 422 for unknown strings, not 200+failed

[dougborg]

Context

While verifying PR #980 assumptions against the live test tenant (2026-07-14), several documented POST /serial_numbers behaviors turned out to be stale. Our spec (CreateSerialNumberResourceType, CreateSerialNumberFailureReason, the endpoint description) and the MCP add_serial_numbers tool describe a graceful 200 + successful/failed arrays model where a non-existent serial string lands in failed with reason: MISSING. The live wire did not behave that way.

Observed (live test tenant, 2026-07-14)

• POST /serial_numbers resource_type=SalesOrderRow, unknown serial string → 422 "serial numbers not found: …" (not 200+failed:MISSING).
• resource_type=Production, unknown string → 422 UnknownSerialNumber.
• Duplicate string, and mixed new+duplicate → 422 UnknownSerialNumber for every string.
• Minting a new string to a freshly-created NOT_STARTED ManufacturingOrder also returned 422 UnknownSerialNumber (nothing attached) — so the "mint types don't need the string to pre-exist" claim is suspect, or minting is MO-state-dependent (serials only mintable once production has run).
• Non-existent resource_id → 404 NotFoundError (already corrected in feat: attach serial numbers via unified traceability input #980).

What needs re-verification

1. Does the 200 + successful/failed partial-outcome shape (CreateSerialNumbersResponse) still occur for any input, or has the endpoint moved to hard 422 on any invalid string?
2. The real mint-vs-transfer boundary and whether minting requires the MO/PO to be in a specific state (e.g. a completed production).
3. Whether CreateSerialNumberFailureReason (DUPLICATE/MISSING) is still reachable, or dead.

Scope note

PR #980 corrected only the claims it directly touched (Production is a valid transfer type; 404 for missing ids; removed the now-false "others return 200+failed" contrast). This issue tracks the fuller re-characterization of the create semantics + response shape, which is out of scope for #980.

[dougborg]

Additional item for the traceability re-verification scope (from #980 review):

Does the wire distinguish an omitted axis from an explicit null on a TraceabilityRequest entry? The MCP TraceabilityInput (and the pre-existing BinTransferTraceabilityInput) map None -> UNSET, so an omitted batch_id/bin_location_id/serial_number_id and an explicit JSON null both collapse to "omit". The spec marks these axes nullable and uses null for unassigned/unbatched/untraced stock (GET /bin_inventory?bin_location_id=null), so if POST traceability input treats {batch_id: null} differently from {} (batch_id absent), the current models can't express it.

Probe: create two otherwise-identical traceability allocations, one omitting batch_id and one sending batch_id: null, and check whether Katana treats them differently. If it does, switch the axis fields to a three-state (int | None | Unset) representation on both the new TraceabilityInput and the existing BinTransferTraceabilityInput.

[dougborg]

Live probe results (test tenant, 2026-07-15)

Probed POST /serial_numbers across resource types and MO states via raw JSON. Every scenario returned 422 — the 200 + successful/failed partial-outcome shape never occurred. No records were created (non-mutating).

Scenario	Request	Result
Unknown string → SalesOrderRow	new string, valid row	422 "serial numbers not found: …"
Unknown string → Production	new string, valid Production id	422 "Unknown serial numbers: …" · errorCode: UnknownSerialNumber
Mint new → ManufacturingOrder (DONE)	new string	422 "… has no remaining quantity — update the batch on its completed productions instead"
Mint new → ManufacturingOrder (IN_PROGRESS)	new string	422 UnknownSerialNumber
Mint new → ManufacturingOrder (NOT_STARTED)	new string	422 UnknownSerialNumber
Mint new → SalesOrderRow	new string	422 "serial numbers not found: …"
Mix [existing, unknown] → MO	one attached + one new	422 (whole request fails)

Answers to the three questions

1. Does 200 + successful/failed still occur for invalid input? No. Every invalid input hard-fails with 422. The failed array with reason: MISSING/DUPLICATE was never produced — strong evidence CreateSerialNumbersResponse.failed + CreateSerialNumberFailureReason are dead on the current API.
2. Mint-vs-transfer boundary / MO-state dependence? There is no working "mint" path through this endpoint. A brand-new string is rejected as UnknownSerialNumber regardless of MO state (DONE / IN_PROGRESS / NOT_STARTED) and regardless of resource type. SalesOrderRow and Production require the string to already exist ("serial numbers not found" / "Unknown serial numbers"). A completed MO additionally rejects with a distinct message pointing at "the batch on its completed productions." Conclusion: POST /serial_numbers is an attach/transfer endpoint over pre-existing serial strings; serials are minted elsewhere (during production / goods receipt), not here.
3. Is CreateSerialNumberFailureReason (DUPLICATE/MISSING) reachable? Not observed. Unknown → 422 … UnknownSerialNumber; the completed-MO duplicate path 422'd on remaining-quantity before any duplicate-detection could surface. No MISSING/DUPLICATE reason code appeared.

One axis still unverified

I did not positively demonstrate a 200 success shape (a valid transfer of an existing serial to an accepting target), because doing so mutates real serial→resource linkages on the tenant. So whether the successful array is still the 200 success envelope is unconfirmed — but the failure path is definitively 422, not 200+failed.

Recommended spec follow-up

• Document POST /serial_numbers as an attach/transfer endpoint that requires pre-existing serial strings and returns 422 UnprocessableEntityError (errorCode: UnknownSerialNumber, structured details[]) on any unknown/invalid string — not a graceful 200+failed.
• Re-evaluate whether CreateSerialNumbersResponse.failed and CreateSerialNumberFailureReason (MISSING/DUPLICATE) should remain in the spec, or be marked dead / removed.
• Capture the completed-MO remaining-quantity error and the "mint happens during production, not here" semantics in the endpoint description.