W097: Create transfer between locations

Records the outbound leg of a materials transfer between two locations. Triggered from the Materials Inventory Transfers page, "New transfer". The single outbound row encodes both source and destination; the inbound leg is added later via W098 when the receiving location confirms arrival.

Steps

1. Validate the material. Confirm it exists and is active.

2. Validate the source and destination locations. Confirm both exist, are active in this org, and are distinct.

3. Write the outbound TRANSFER row. Call MaterialsInventory.recordTransfer({ materialId, locationId: sourceLocationId, toLocationId: destinationLocationId, quantity, eventDate, notes }). The L2 op auto-generates a per-tenant TFR-MI-NNN ref and returns it. The row stores location_id = sourceLocationId, to_location_id = destinationLocationId, quantity = quantity (positive; the L1 schema requires it), event_type = 'TRANSFER'. Direction is encoded in event_type; the summary query treats TRANSFER as outflow at location_id and (when paired with a RECEIVE) inflow at to_location_id.

Returns

The outbound TRANSFER row plus the generated ref.

Business rules

• Single row encodes both ends. The TRANSFER row carries the source in location_id and destination in to_location_id. The destination is fixed at creation; if shipments get diverted the user cancels and re-creates rather than editing.
• Quantities are always positive. The L1 schema mandates quantity > 0; the TRANSFER event type itself encodes "outflow at location_id, expected inflow at to_location_id". The summary query interprets the sign.
• In-transit derivation. A transfer is "in transit" while its outbound TRANSFER row exists without a matching RECEIVE row (matched by ref). The in-transit summary uses to_location_id to attribute the inbound quantity to the destination.
• No stock guard in v1. The workflow does not block on insufficient source stock; the ledger goes negative if a user transfers more than they have.

Errors

• NotFoundError. The material or a location was not found.
• ValidationError. Source and destination are the same.