fix(assets): consume ONE_WAY stock on custody release, gate activity notes server-side

apps/companion/app/(tabs)/assets/[id].tsx

@@ -15,6 +15,7 @@ import * as Haptics from "expo-haptics";
 import { Image } from "expo-image";
 import { useLocalSearchParams, useRouter, Stack } from "expo-router";
 import { Ionicons } from "@expo/vector-icons";
+import { releaseCategory } from "@shelf/quantity-control";
 import {
   api,
   type AssetCustodyListEntry,
@@ -314,6 +315,10 @@ export default function AssetDetailScreen() {
   const releaseMax = releaseQtyEntry
     ? releaseQtyEntry.releasableQuantity ?? releaseQtyEntry.quantity
     : 0;
+  // The shared predicate decides this, so the wording can never disagree with
+  // what the server does. Servers predating the field send no consumptionType,
+  // which falls through to the returnable copy — the server's own default.
+  const isConsumable = releaseCategory(asset.consumptionType) === "CONSUME";
   // Custody holders the server hid from this caller (privacy filtering for
   // roles without view-all-custody). Shown as a muted "+N others" row.
   const custodyOthersCount = isQtyTracked
@@ -498,9 +503,13 @@ export default function AssetDetailScreen() {
                     }
                     accessibilityLabel={
                       canReleaseRow
-                        ? `Release custody from ${
-                            entry.custodian.name
-                          }, holds ${qtyLabel ?? entry.quantity}`
+                        ? isConsumable
+                          ? `End hold on units held by ${
+                              entry.custodian.name
+                            }, holds ${qtyLabel ?? entry.quantity}`
+                          : `Release custody from ${
+                              entry.custodian.name
+                            }, holds ${qtyLabel ?? entry.quantity}`
                         : undefined
                     }
                   />
@@ -753,28 +762,49 @@ export default function AssetDetailScreen() {
               />
               <QuantityInputSheet
                 visible={releaseQtyEntry != null}
-                title="Release Quantity"
+                title={isConsumable ? "End hold" : "Release Quantity"}
                 subtitle={
                   releaseQtyEntry
-                    ? `Release how many of ${
-                        releaseQtyEntry.custodian.name
-                      }'s ${
-                        formatQuantity(releaseMax, asset.unitOfMeasure) ??
-                        String(releaseMax)
-                      }?`
+                    ? isConsumable
+                      ? `End the hold on how many of ${
+                          releaseQtyEntry.custodian.name
+                        }'s ${
+                          formatQuantity(releaseMax, asset.unitOfMeasure) ??
+                          String(releaseMax)
+                        }, and how many were used up? Used-up units permanently reduce total stock.`
+                      : `Release how many of ${
+                          releaseQtyEntry.custodian.name
+                        }'s ${
+                          formatQuantity(releaseMax, asset.unitOfMeasure) ??
+                          String(releaseMax)
+                        }?`
                     : undefined
                 }
                 max={releaseMax}
                 // Web parity: the release dialog pre-fills a full release.
                 defaultValue={releaseMax}
                 unitOfMeasure={asset.unitOfMeasure}
-                confirmLabel="Release"
+                secondary={
+                  isConsumable
+                    ? {
+                        label: "Of those, how many were used up?",
+                        // Pre-fill a full consume — the common case, and what
+                        // the server defaults to when no split is sent.
+                        defaultValue: releaseMax,
+                      }
+                    : undefined
+                }
+                confirmLabel={isConsumable ? "Confirm" : "Release"}
                 destructive
-                onSubmit={(quantity) => {
+                onSubmit={(quantity, consumed) => {
                   const entry = releaseQtyEntry;
                   setReleaseQtyEntry(null);
                   if (entry) {
-                    void performReleaseQuantity(entry.custodian.id, quantity);
+                    void performReleaseQuantity(
+                      entry.custodian.id,
+                      quantity,
+                      consumed
+                    );
                   }
                 }}
                 onClose={() => setReleaseQtyEntry(null)}

apps/companion/components/quantity-input-sheet.tsx

@@ -38,6 +38,18 @@ type Props = {
   defaultValue?: number;
   /** Display unit echoed under the input (e.g. "pcs"); null/undefined hides it. */
   unitOfMeasure?: string | null;
+  /**
+   * Optional second numeric field rendered under the primary one. The ONE_WAY
+   * custody release uses it to ask how many of the released units were used
+   * up. Its value is clamped to the primary quantity, so it can never
+   * over-claim.
+   */
+  secondary?: {
+    /** Field label, e.g. "Of those, how many were used up?". */
+    label: string;
+    /** Initial value when the sheet opens (clamped to [0, primary]). */
+    defaultValue?: number;
+  };
   /** Confirm button label, e.g. "Assign" / "Release". */
   confirmLabel: string;
   /**
@@ -46,8 +58,11 @@ type Props = {
    * quick-actions.tsx `primaryActionGreen`). Default is the primary black.
    */
   destructive?: boolean;
-  /** Called with the validated quantity when the user confirms. */
-  onSubmit: (quantity: number) => void;
+  /**
+   * Called with the validated quantity when the user confirms, plus the
+   * secondary value when a `secondary` field is configured.
+   */
+  onSubmit: (quantity: number, secondaryValue?: number) => void;
   /** Called when the user dismisses the sheet without confirming. */
   onClose: () => void;
 };
@@ -69,6 +84,7 @@ export function QuantityInputSheet({
   max,
   defaultValue,
   unitOfMeasure,
+  secondary,
   confirmLabel,
   destructive,
   onSubmit,
@@ -78,22 +94,50 @@ export function QuantityInputSheet({
   const styles = useStyles();
 
   const [value, setValue] = useState("1");
+  const [secondaryValue, setSecondaryValue] = useState("0");
   const inputRef = useRef<TextInput>(null);
 
-  // Re-seed the input every time the sheet opens: each open targets a fresh
+  // The secondary field's presence and seed are read out as primitives so the
+  // re-seed effect below can depend on THEM rather than on the `secondary`
+  // object. Callers build that object inline, giving it a fresh identity on
+  // every parent render — as a dependency it would turn "re-seed on open" into
+  // "re-seed on every parent render", silently discarding a split the operator
+  // had already typed.
+  const hasSecondaryField = secondary != null;
+  const secondaryDefaultValue = secondary?.defaultValue;
+
+  // Re-seed the inputs every time the sheet opens: each open targets a fresh
   // action (different member/holder), so stale values must not leak across.
   useEffect(() => {
     if (visible) {
       const seed = Math.min(Math.max(defaultValue ?? 1, 1), Math.max(max, 1));
       setValue(String(seed));
+      if (hasSecondaryField) {
+        // Clamp the secondary seed to the primary seed — the two fields move
+        // together and the secondary can never exceed the units being released.
+        setSecondaryValue(
+          String(Math.min(Math.max(secondaryDefaultValue ?? 0, 0), seed))
+        );
+      }
     }
-  }, [visible, defaultValue, max]);
+  }, [visible, defaultValue, max, hasSecondaryField, secondaryDefaultValue]);
 
   const parsed = value ? parseInt(value, 10) : NaN;
   const hasValue = Number.isFinite(parsed);
   const overMax = hasValue && parsed > max;
   const isValid = hasValue && parsed >= 1 && parsed <= max;
 
+  const parsedSecondary = secondaryValue ? parseInt(secondaryValue, 10) : NaN;
+  const hasSecondary = Number.isFinite(parsedSecondary);
+  // With no secondary field the sheet behaves exactly as it always has.
+  const isSecondaryValid =
+    !secondary ||
+    (hasSecondary &&
+      parsedSecondary >= 0 &&
+      hasValue &&
+      parsedSecondary <= parsed);
+  const canConfirm = isValid && isSecondaryValid;
+
   /** Step the current value by `delta`, clamped to [1, max]. */
   const step = (delta: number) => {
     const current = hasValue ? parsed : 0;
@@ -188,20 +232,46 @@ export function QuantityInputSheet({
             </Text>
           )}
 
+          {/* Optional second field, e.g. how many released units were used up */}
+          {secondary ? (
+            <View style={styles.secondaryBlock}>
+              <Text style={styles.secondaryLabel}>{secondary.label}</Text>
+              <TextInput
+                style={styles.input}
+                value={secondaryValue}
+                onChangeText={(text) => {
+                  setSecondaryValue(text.replace(/[^0-9]/g, ""));
+                }}
+                placeholder="0"
+                placeholderTextColor={colors.placeholderText}
+                keyboardType="number-pad"
+                returnKeyType="done"
+                accessibilityLabel={secondary.label}
+              />
+              {!isSecondaryValid ? (
+                <Text style={styles.errorHint}>
+                  Cannot exceed the {hasValue ? parsed : 0} being released.
+                </Text>
+              ) : null}
+            </View>
+          ) : null}
+
           {/* Confirm */}
           <TouchableOpacity
             style={[
               destructive ? styles.confirmRelease : styles.confirmPrimary,
-              !isValid && styles.confirmDisabled,
+              !canConfirm && styles.confirmDisabled,
             ]}
             onPress={() => {
-              if (isValid) onSubmit(parsed);
+              if (canConfirm) {
+                onSubmit(parsed, secondary ? parsedSecondary : undefined);
+              }
             }}
-            disabled={!isValid}
+            disabled={!canConfirm}
             activeOpacity={0.7}
             accessibilityLabel={`${confirmLabel} ${echo ?? "quantity"}`}
             accessibilityRole="button"
-            accessibilityState={{ disabled: !isValid }}
+            accessibilityState={{ disabled: !canConfirm }}
           >
             <Text style={styles.confirmText}>{confirmLabel}</Text>
           </TouchableOpacity>
@@ -280,6 +350,14 @@ const useStyles = createStyles((colors, shadows) => ({
     color: colors.muted,
     textAlign: "center",
   },
+  secondaryBlock: {
+    marginTop: spacing.md,
+    gap: spacing.xs,
+  },
+  secondaryLabel: {
+    fontSize: fontSize.sm,
+    color: colors.muted,
+  },
   errorHint: {
     fontSize: fontSize.sm,
     color: colors.error,

apps/companion/hooks/use-custody-actions.ts

@@ -27,10 +27,15 @@ interface UseCustodyActionsReturn {
    * Release `quantity` units of a QUANTITY_TRACKED asset from the custodian
    * identified by `custodianId` (team-member id). Confirmed by the sheet,
    * same as `performAssignQuantity`.
+   *
+   * `consumed` records how many of those units were used up rather than
+   * handed back. Omit it and the server derives the outcome from the asset's
+   * consumptionType.
    */
   performReleaseQuantity: (
     custodianId: string,
-    quantity: number
+    quantity: number,
+    consumed?: number
   ) => Promise<void>;
 }
 
@@ -142,7 +147,8 @@ export function useCustodyActions({
 
   const performReleaseQuantity = async (
     custodianId: string,
-    quantity: number
+    quantity: number,
+    consumed?: number
   ) => {
     if (!currentOrg || !asset) return;
     setIsActionLoading(true);
@@ -151,7 +157,8 @@ export function useCustodyActions({
         currentOrg.id,
         asset.id,
         custodianId,
-        quantity
+        quantity,
+        { consumed }
       );
       if (err) Alert.alert("Error", err);
       else {

apps/companion/lib/api/custody.ts

@@ -65,23 +65,33 @@ export const custodyApi = {
   },
 
   /**
-   * Release N units of a QUANTITY_TRACKED asset from a team member's custody.
-   * Mobile twin of the web's /api/assets/release-quantity-custody — only
+   * End a team member's hold on N units of a QUANTITY_TRACKED asset. Mobile
+   * twin of the web's /api/assets/release-quantity-custody — only
    * operator-assigned units are releasable (kit-allocated units are cleared
    * by releasing the kit's custody); the server enforces the held cap.
+   *
+   * `options.consumed` records how many of the released units were used up.
+   * Omit it and the server derives the outcome from the asset's
+   * consumptionType, so an older build still behaves correctly.
    */
   releaseQuantityCustody: async (
     orgId: string,
     assetId: string,
     teamMemberId: string,
     quantity: number,
-    note?: string
+    options?: { consumed?: number; note?: string }
   ) => {
     const result = await apiFetch<QuantityCustodyResponse>(
       `/api/mobile/custody/release-quantity?orgId=${orgId}`,
       {
         method: "POST",
-        body: JSON.stringify({ assetId, teamMemberId, quantity, note }),
+        body: JSON.stringify({
+          assetId,
+          teamMemberId,
+          quantity,
+          consumed: options?.consumed,
+          note: options?.note,
+        }),
         // why: non-idempotent — a timed-out-but-landed request must not be
         // auto-retried, or the release double-applies.
         retry: false,

apps/companion/package.json

@@ -32,6 +32,7 @@
     "@sentry/react-native": "~7.2.0",
     "@shelf/datetime": "workspace:*",
     "@shelf/labels": "workspace:*",
+    "@shelf/quantity-control": "workspace:*",
     "@supabase/supabase-js": "^2.49.1",
     "expo": "~54.0.33",
     "expo-av": "^16.0.8",