Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

188 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

import {
  CarbonError,
  createServiceContext,
  defineServiceFn
} from "@carbon/api/service-fn.server";
import { paged, payload, run, unwrap } from "@carbon/api/service-tools.server";
import type { Json } from "@carbon/database";
import { convertUnitPrice } from "@carbon/database/supplier-part-price";
import {
  dedupeViolations,
  evaluateSalesRuleLines,
  isBlocked,
  resolveSalesOrderShipTo
} from "@carbon/ee/rules.server";
import { trackWorkEvent } from "@carbon/lib/telemetry";
import { raiseMoment } from "@carbon/lib/workflows";
import { getLogger } from "@carbon/logger";
import { runLocationSchedule } from "@carbon/planning";
import {
  datetime,
  getErrorMessage,
  getOverReceiptViolations,
  isUniqueViolation,
  round,
  type Violation
} from "@carbon/utils";
import { parseDate } from "@internationalized/date";
import { z } from "zod";
import { getItemReplenishment } from "~/modules/items/items.service";
import { getSupplierPartPricing } from "~/modules/items/items.utils";
import { releaseCheckedJobs } from "~/modules/production/production.server";
import {
  getActiveJobOperationByJobId,
  getJobReleaseReadiness,
  insertJob,
  updateKanbanJob,
  upsertJobMethod
} from "~/modules/production/production.service";
import { jobReleaseProblems } from "~/modules/production/ui/Jobs/job-release-logic";
import {
  insertPurchaseOrder,
  updatePurchasedPrices,
  upsertPurchaseOrderLine
} from "~/modules/purchasing/purchasing.service";
import { recordSalesRuleOutcome } from "~/modules/sales/sales.service";
import {
  getCompanySettings,
  getNextSequence
} from "~/modules/settings/settings.service";
import {
  booleanField,
  optionalTiptapDoc
} from "~/modules/shared/shared.models";
import {
  getCompanyTimeZone,
  getLocationTimeZone,
  invokeCreate,
  invokePosting,
  refuseUnlessOwned
} from "~/modules/shared/shared.service";
import { resolveSupplierPrice } from "~/modules/shared/shared.utils";
import {
  finishPickingList,
  inventoryAdjustmentTypes,
  inventoryCountStatusFrom,
  inventoryItemTypes,
  isPickingListLocked,
  isStockTransferLocked,
  pickingListStatusType,
  receiptFixedAssetLineUpdateValidator,
  receiptSourceDocumentType,
  resolveStockTransferPickForward,
  shipmentFixedAssetLineUpdateValidator,
  shipmentSourceDocumentType,
  stockTransferStatusType,
  warehouseTransferStatusType
} from "./inventory.models";
import type { Blocked } from "./inventory.service";
import * as service from "./inventory.service";
import * as utils from "./inventory.utils";
import { getDefaultStorageUnitForJob } from "./inventory.utils";

const logger = getLogger("erp", "inventory");

// ---------------------------------------------------------------------------
// Shared steps
// ---------------------------------------------------------------------------
const customFieldsInput = z
  .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
  .optional();
const RECEIPT_NOT_FOUND = "The receipt could not be found";
const RECEIPT_LOCKED = "A posted receipt can no longer be changed";
// A read by id runs under RLS, which admits every company the caller belongs
// to: another company's row reads like a missing one.
const NOT_FOUND = "No matching record was found.";

// ---------------------------------------------------------------------------
// Receipts
// ---------------------------------------------------------------------------

/**
 * Create a receipt.
 *
 * @remarks
 * From its source document, with its lines: a purchase order, a sales return
 * order, an inbound warehouse transfer or a rental agreement. With no source
 * document it creates an empty receipt. The location is the caller's default
 * location; a sales return falls back to the return order's own.
 *
 * A sales return order or rental agreement with a Draft receipt already
 * returns that receipt instead of a second one.
 *
 * @mcp
 */
export const createReceipt = defineServiceFn({
  input: z.object({
    sourceDocument: z.enum(receiptSourceDocumentType).optional(),
    sourceDocumentId: z.string().default("")
  }),
  permission: { create: "inventory" },

  async run(ctx, { sourceDocument, sourceDocumentId }) {
    const locationId = await service.defaultLocationOf(ctx);

    // One open draft per return order or agreement: a second Receive goes to
    // the existing draft instead of stacking up duplicates.
    if (
      sourceDocument === "Sales Return Order" ||
      sourceDocument === "Rental Agreement"
    ) {
      const existing = await ctx.asCaller.supabase
        .from("receipt")
        .select("id")
        .eq("sourceDocument", sourceDocument)
        .eq("sourceDocumentId", sourceDocumentId)
        .eq("status", "Draft")
        .eq("companyId", ctx.company.id)
        .order("createdAt", { ascending: false })
        .limit(1)
        .maybeSingle();
      if (existing.error) {
        return ctx.error(
          "internal",
          "Failed to check for an existing receipt",
          existing.error
        );
      }
      if (existing.data) return { id: existing.data.id };
    }

    const created = await (() => {
      switch (sourceDocument) {
        case "Purchase Order":
          return invokeCreate(ctx, {
            type: "receiptFromPurchaseOrder",
            locationId,
            purchaseOrderId: sourceDocumentId,
            receiptId: undefined
          });
        case "Sales Return Order":
          // No default-location guard: the server function falls back to the
          // return order's own location and errors specifically otherwise.
          return invokeCreate(ctx, {
            type: "receiptFromSalesReturnOrder",
            locationId,
            salesReturnOrderId: sourceDocumentId,
            receiptId: undefined
          });
        case "Inbound Transfer":
          return invokeCreate(ctx, {
            type: "receiptFromInboundTransfer",
            warehouseTransferId: sourceDocumentId,
            receiptId: undefined
          });
        case "Rental Agreement":
          return invokeCreate(ctx, {
            type: "receiptFromRentalAgreement",
            rentalAgreementId: sourceDocumentId
          });
        default:
          return invokeCreate(ctx, {
            type: "receiptDefault",
            locationId: locationId as string
          });
      }
    })();
    if (created.error || !created.data) {
      // Only the return and rental paths ever named the reason.
      const named =
        sourceDocument === "Sales Return Order" ||
        sourceDocument === "Rental Agreement";
      return service.serverFnFailure(
        ctx,
        created.error,
        named
          ? getErrorMessage(created.error, "Failed to create receipt")
          : "Failed to create receipt"
      );
    }
    return { id: created.data.id };
  }
});

/**
 * Update a receipt's details.
 *
 * @remarks
 * A changed source document or location rebuilds the receipt's lines from
 * the new source (a purchase order, a sales return order or an inbound
 * transfer), and is refused once the receipt is not Draft. Otherwise the
 * fields are saved as sent. A rental receipt keeps its rental agreement:
 * changing it is refused.
 *
 * @mcp
 */
export const updateReceipt = defineServiceFn({
  input: z.object({
    id: z.string(),
    receiptId: z.string().min(1),
    locationId: z.string().optional(),
    sourceDocument: z.enum(receiptSourceDocumentType).optional(),
    sourceDocumentId: z.string().min(1),
    externalDocumentId: z.string().optional(),
    sourceDocumentReadableId: z.string().optional(),
    supplierId: z.string().optional(),
    customFields: customFieldsInput
  }),
  permission: { update: "inventory" },

  async run(ctx, { id, ...receipt }) {
    const current = await ctx.asCaller.supabase
      .from("receipt")
      .select("sourceDocument, sourceDocumentId, locationId, status")
      .eq("id", id)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (current.error) {
      return ctx.error("internal", "Failed to load receipt", current.error);
    }
    if (!current.data) return ctx.error("notFound", RECEIPT_NOT_FOUND);

    const sourceChanged =
      current.data.sourceDocument !== receipt.sourceDocument ||
      current.data.sourceDocumentId !== receipt.sourceDocumentId;
    const isRental =
      current.data.sourceDocument === "Rental Agreement" ||
      receipt.sourceDocument === "Rental Agreement";
    if (isRental && sourceChanged) {
      return ctx.error(
        "rule",
        "A rental receipt keeps its rental agreement. Create it from the agreement."
      );
    }

    const rebuild =
      !isRental &&
      (sourceChanged || current.data.locationId !== receipt.locationId);
    // A rebuild replaces the lines: on a posted receipt, the posted ones.
    if (rebuild && current.data.status !== "Draft") {
      return ctx.error(
        "rule",
        "Only a Draft receipt can change its source document or location"
      );
    }
    if (!rebuild) {
      const updated = await service.upsertReceipt(ctx.asCaller.supabase, {
        id,
        ...receipt,
        updatedBy: ctx.auditUserId
      });
      if (updated.error) {
        return ctx.error("internal", "Failed to update receipt", updated.error);
      }
      return { id };
    }

    const created = await (() => {
      switch (receipt.sourceDocument) {
        case "Purchase Order":
          return invokeCreate(ctx, {
            type: "receiptFromPurchaseOrder",
            locationId: receipt.locationId,
            purchaseOrderId: receipt.sourceDocumentId,
            receiptId: id
          });
        case "Sales Return Order":
          return invokeCreate(ctx, {
            type: "receiptFromSalesReturnOrder",
            locationId: receipt.locationId,
            salesReturnOrderId: receipt.sourceDocumentId,
            receiptId: id
          });
        case "Inbound Transfer":
          return invokeCreate(ctx, {
            type: "receiptFromInboundTransfer",
            warehouseTransferId: receipt.sourceDocumentId,
            receiptId: id
          });
        default:
          return null;
      }
    })();
    if (!created) {
      return ctx.error("validation", "Unsupported source document");
    }
    if (created.error || !created.data) {
      return service.serverFnFailure(
        ctx,
        created.error,
        "Failed to create receipt"
      );
    }
    return { id };
  }
});

/**
 * Post a receipt.
 *
 * @remarks
 * In order:
 *   1. A Posted or Voided receipt is refused (`conflict`): posting it again
 *      would duplicate its ledger entries, cost layers and journal lines.
 *   2. Storage rules run on the `receipt` and `place` surfaces (and
 *      `warehouseTransfer` for an inbound transfer), and a purchase order
 *      receipt is checked for over-receipt against the live order lines. A
 *      blocking rule returns its `violations` and `ruleNames` and changes
 *      nothing; send `acknowledged: true` to post past warnings.
 *   3. The receipt is set Pending (only from Draft or Pending: `conflict`
 *      otherwise).
 *   4. Stale serial entities on serial-tracked lines are deleted, so they
 *      are not made Available as phantom serials, and the receipt is posted:
 *      ledger entries, cost layers, the journal and tracked entities. A
 *      failed post sets it back to Draft.
 *   5. Supplier lead times are refreshed when the company setting is on,
 *      labels print when the receiving printer auto-prints, and the
 *      receipt-posted workflow moment is raised.
 *
 * `postingDate` dates a rental return; every other receipt posts today.
 *
 * @mcp
 */
export const postReceipt = defineServiceFn({
  input: z.object({
    receiptId: z.string(),
    acknowledged: z.boolean().default(false),
    postingDate: z.string().optional()
  }),
  permission: { update: "inventory" },

  async run(ctx, { receiptId, acknowledged, postingDate }) {
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;
    // As the system: a user with `inventory` rights may not see the items,
    // bins or purchase order lines the checks read.
    const serviceRole = ctx.asSystem.supabase;

    const [lines, receipt] = await Promise.all([
      serviceRole
        .from("receiptLine")
        .select(
          "id, itemId, storageUnitId, receivedQuantity, locationId, receiptId, requiresSerialTracking, lineId, conversionFactor"
        )
        .eq("receiptId", receiptId)
        .eq("companyId", companyId),
      serviceRole
        .from("receipt")
        .select("sourceDocument, sourceDocumentId, status, locationId")
        .eq("id", receiptId)
        .eq("companyId", companyId)
        .maybeSingle()
    ]);
    if (!receipt.data) return ctx.error("notFound", RECEIPT_NOT_FOUND);
    if (receipt.data.status === "Posted") {
      return ctx.error("conflict", "This receipt has already been posted");
    }
    if (receipt.data.status === "Voided") {
      return ctx.error("conflict", "This receipt has been voided");
    }

    const isTransfer = receipt.data.sourceDocument === "Inbound Transfer";
    const ruleLines = (lines.data ?? []).map((line) => ({
      lineId: line.id,
      itemId: line.itemId,
      storageUnitId: line.storageUnitId,
      quantity: Number(line.receivedQuantity ?? 0),
      locationId: line.locationId
    }));
    // The transfer surface rides with both passes: the post completes the
    // parent transfer. Dedupe collapses the overlap.
    const rules = await service.storageRuleViolations(
      ctx,
      isTransfer
        ? ["receipt", "warehouseTransfer", "place", "warehouseTransfer"]
        : ["receipt", "place"],
      ruleLines
    );

    // Over-receipt is checked against the live purchase order lines, not the
    // receipt's snapshot, so concurrent receipts are counted.
    if (receipt.data.sourceDocument === "Purchase Order") {
      const purchaseOrderLineIds = [
        ...new Set(
          (lines.data ?? [])
            .map((line) => line.lineId)
            .filter((id): id is string => Boolean(id))
        )
      ];
      if (purchaseOrderLineIds.length > 0) {
        const purchaseOrderLines = await serviceRole
          .from("purchaseOrderLine")
          .select(
            "id, purchaseQuantity, quantityReceived, item(readableIdWithRevision)"
          )
          .in("id", purchaseOrderLineIds)
          .eq("companyId", companyId);
        const overReceipt = getOverReceiptViolations(
          lines.data ?? [],
          (purchaseOrderLines.data ?? []).map((line) => ({
            id: line.id,
            purchaseQuantity: line.purchaseQuantity,
            quantityReceived: line.quantityReceived,
            itemReadableId: line.item?.readableIdWithRevision
          }))
        );
        rules.violations.push(...overReceipt.violations);
        Object.assign(rules.ruleNames, overReceipt.ruleNames);
      }
    }

    const violations = dedupeViolations(rules.violations);
    if (violations.length > 0 && isBlocked(violations, acknowledged)) {
      return { violations, ruleNames: rules.ruleNames } satisfies Blocked;
    }

    // Conditional on a postable status, so a concurrent void or post is not
    // flipped back to Pending, and nothing below touches a posted receipt.
    const pending = await ctx.asCaller.supabase
      .from("receipt")
      .update({ status: "Pending" })
      .eq("id", receiptId)
      .eq("companyId", companyId)
      .in("status", ["Draft", "Pending"])
      .select("id");
    if (pending.error) {
      return ctx.error("internal", "Failed to post receipt", pending.error);
    }
    if (!pending.data?.length) {
      return ctx.error(
        "conflict",
        "This receipt has already been posted or voided"
      );
    }

    // Only from Pending: a concurrent post that won must stay Posted.
    const backToDraft = () =>
      ctx.asCaller.supabase
        .from("receipt")
        .update({ status: "Draft" })
        .eq("id", receiptId)
        .eq("companyId", companyId)
        .eq("status", "Pending");

    let failure: CarbonError | null = null;
    try {
      const { linesMissingSerials } =
        await service.reconcileReceiptSerialEntities(ctx.asSystem.pg, {
          receiptId,
          companyId,
          isSalesReturn: receipt.data.sourceDocument === "Sales Return Order",
          lines: lines.data ?? []
        });
      if (linesMissingSerials.length > 0) {
        await backToDraft();
        return ctx.error("rule", "Serial numbers are missing");
      }
      const posted = await invokePosting(
        ctx,
        "post-receipt",
        {
          receiptId,
          postingDate
        },
        service.postReceipt
      );
      if (posted.error) {
        await backToDraft();
        // Below 500 the posting refused the receipt, in words for the person.
        return posted.error.status < 500
          ? service.serverFnFailure(
              ctx,
              posted.error,
              posted.error.message || "Failed to post receipt"
            )
          : ctx.error("internal", "Failed to post receipt", posted.error);
      }
    } catch (thrown) {
      await backToDraft();
      failure = ctx.error("internal", "Failed to post receipt", thrown);
    }

    if (!failure) {
      const settings = await serviceRole
        .from("companySettings")
        .select("updateLeadTimesOnReceipt")
        .eq("id", companyId)
        .single();
      if (
        settings.data?.updateLeadTimesOnReceipt &&
        receipt.data.sourceDocument === "Purchase Order" &&
        receipt.data.sourceDocumentId
      ) {
        // System: the poster needs no purchasing rights to refresh lead times.
        const leadTimes = await invokePosting(
          ctx,
          "update-purchased-prices",
          {
            source: "purchaseOrder",
            purchaseOrderId: receipt.data.sourceDocumentId,
            updatePrices: false,
            updateLeadTimes: true
          },
          updatePurchasedPrices
        );
        if (leadTimes.error) {
          logger.error("Failed to update lead time on receipt posting", {
            error: leadTimes.error
          });
        }
      }

      await service.autoPrint(ctx, {
        sourceDocument: "Receipt",
        sourceDocumentId: receiptId,
        locationId: receipt.data.locationId,
        context: "receiving"
      });
    }

    // Raised after a rollback to Draft too: when workflows fire is its own
    // decision (#1294), unchanged here.
    await raiseMoment("inventory.receiptPosted", {
      outputs: { receipt: { id: receiptId }, postedBy: { id: userId } },
      companyId,
      actorId: userId
    });

    if (failure) return failure;
    trackWorkEvent("receipt_posted", {
      companyId,
      userId,
      receiptId,
      sourceDocument: receipt.data.sourceDocument ?? null
    });
    return { posted: true as const };
  }
});

/**
 * Void a posted receipt.
 *
 * @remarks
 * Reverses its inventory adjustments and journal entries, restores its
 * tracked entities and the purchase order quantities. Only a Posted receipt
 * can be voided, and not one a purchase invoice created: void the invoice
 * instead.
 *
 * @mcp destructive
 */
export const voidReceipt = defineServiceFn({
  input: z.object({ receiptId: z.string() }),
  permission: { update: "inventory" },

  async run(ctx, { receiptId }) {
    const receipt = await ctx.asCaller.supabase
      .from("receipt")
      .select("status, invoiced")
      .eq("id", receiptId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (receipt.error) {
      return ctx.error("internal", "Failed to void receipt", receipt.error);
    }
    if (!receipt.data) return ctx.error("notFound", "Receipt not found");
    if (receipt.data.status !== "Posted") {
      return ctx.error("rule", "Can only void posted receipts");
    }
    if (receipt.data.invoiced) {
      return ctx.error(
        "rule",
        "Cannot void a receipt created by a purchase invoice. Void the invoice instead."
      );
    }

    const voided = await invokePosting(
      ctx,
      "post-receipt",
      {
        type: "void",
        receiptId
      },
      service.postReceipt
    );
    if (voided.error) {
      // Below 500 the posting refused the void, in words for the person.
      return voided.error.status < 500
        ? service.serverFnFailure(
            ctx,
            voided.error,
            voided.error.message || "Failed to void receipt"
          )
        : ctx.error("internal", "Failed to void receipt", voided.error);
    }
    return { receiptId };
  }
});

/**
 * Split a receipt line in two.
 *
 * @remarks
 * Moves `quantity` of the line onto a new line of the same receipt, so the
 * two can go to different storage units or carry different tracking.
 *
 * @mcp
 */
export const splitReceiptLine = defineServiceFn({
  input: z.object({
    receiptId: z.string().min(1),
    receiptLineId: z.string().min(1),
    locationId: z.string().min(1),
    quantity: z.number()
  }),
  permission: { update: "inventory" },

  async run(ctx, { receiptId, receiptLineId, locationId, quantity }) {
    const line = await ctx.asCaller.supabase
      .from("receiptLine")
      .select("id, receipt!receiptLine_receiptId_fkey(status)")
      .eq("id", receiptLineId)
      .eq("receiptId", receiptId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (line.error) {
      return ctx.error("internal", "Failed to split line", line.error);
    }
    if (!line.data?.receipt) {
      return ctx.error("notFound", "The receipt line could not be found");
    }
    if (line.data.receipt.status !== "Draft") {
      return ctx.error("rule", RECEIPT_LOCKED);
    }

    const split = await invokeCreate(ctx, {
      type: "receiptLineSplit",
      locationId,
      receiptId,
      receiptLineId,
      quantity
    });
    if (split.error) {
      return service.serverFnFailure(ctx, split.error, "Failed to split line");
    }
    return { receiptLineId };
  }
});

/**
 * Set one field on receipt lines.
 *
 * @remarks
 * `storageUnitId` or `receivedQuantity`, on every line in `ids`. An empty
 * value clears the field. Storage rules run when the receipt is posted, not
 * here.
 *
 * @mcp
 */
export const updateReceiptLines = defineServiceFn({
  input: z.object({
    ids: z.array(z.string()).min(1),
    field: z.enum(["storageUnitId", "receivedQuantity"]),
    value: z.string().nullable()
  }),
  permission: { update: "inventory" },

  async run(ctx, { ids, field, value }) {
    const lines = await ctx.asCaller.supabase
      .from("receiptLine")
      .select("id, receipt!receiptLine_receiptId_fkey(status)")
      .in("id", ids)
      .eq("companyId", ctx.company.id);
    if (lines.error) {
      return ctx.error("internal", "Failed to load receipt lines", lines.error);
    }
    if (lines.data.length !== new Set(ids).size) {
      return ctx.error("notFound", "The receipt line could not be found");
    }
    if (lines.data.some((line) => line.receipt?.status !== "Draft")) {
      return ctx.error("rule", RECEIPT_LOCKED);
    }

    if (field === "receivedQuantity") {
      const receivedQuantity = Number(value || 0);
      if (!Number.isFinite(receivedQuantity)) {
        return ctx.error("validation", "Received quantity must be a number");
      }
      // Drop serials beyond the new quantity in the same transaction.
      try {
        await ctx.asSystem.pg.transaction().execute(async (trx) => {
          const updated = await trx
            .updateTable("receiptLine")
            .set({
              receivedQuantity,
              updatedBy: ctx.auditUserId,
              updatedAt: datetime.timestamp()
            })
            .where("id", "in", ids)
            .where("companyId", "=", ctx.company.id)
            .returning([
              "id",
              "receiptId",
              "receivedQuantity",
              "requiresSerialTracking"
            ])
            .execute();
          if (updated.length === 0) return;

          const receipts = await trx
            .selectFrom("receipt")
            .select(["id", "sourceDocument"])
            .where("id", "in", [...new Set(updated.map((l) => l.receiptId))])
            .where("companyId", "=", ctx.company.id)
            .where("status", "=", "Draft")
            .execute();
          for (const receipt of receipts) {
            await service.reconcileReceiptSerialsInTransaction(trx, {
              receiptId: receipt.id,
              companyId: ctx.company.id,
              isSalesReturn: receipt.sourceDocument === "Sales Return Order",
              lines: updated.filter((l) => l.receiptId === receipt.id)
            });
          }
        });
      } catch (error) {
        return ctx.error("internal", "Failed to update receipt lines", error);
      }
      return { ids };
    }

    const update = await ctx.asCaller.supabase
      .from("receiptLine")
      .update({
        storageUnitId: value || null,
        updatedBy: ctx.auditUserId,
        updatedAt: datetime.timestamp()
      })
      .in("id", ids)
      .eq("companyId", ctx.company.id);
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update receipt lines",
        update.error
      );
    }
    return { ids };
  }
});

/**
 * Update one field of a fixed-asset line on a receipt.
 *
 * @remarks
 * `received`, `serialNumber`, `meter`, `notes`, `outOfService` (an empty
 * value returns the unit to service, any other text is the reason) or
 * `residualDestination`. A posted or voided receipt is a record: its lines no
 * longer change.
 *
 * @mcp
 */
export const updateReceiptFixedAssetLine = defineServiceFn({
  input: receiptFixedAssetLineUpdateValidator,
  permission: { update: "inventory" },

  async run(ctx, { id, ...change }) {
    const serviceRole = ctx.asSystem.supabase;
    const line = await serviceRole
      .from("receiptFixedAssetLine")
      .select("receipt!receiptFixedAssetLine_receiptId_fkey(status)")
      .eq("id", id)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (line.error || !line.data?.receipt) {
      return ctx.error("notFound", "The receipt line could not be found");
    }
    if (line.data.receipt.status !== "Draft") {
      return ctx.error("rule", "A posted receipt can no longer be changed");
    }

    const update = await serviceRole
      .from("receiptFixedAssetLine")
      .update({
        ...service.receiptFixedAssetLineChange(change),
        updatedBy: ctx.auditUserId
      })
      .eq("id", id)
      .eq("companyId", ctx.company.id);
    if (update.error) {
      return ctx.error("internal", "Failed to update the line", update.error);
    }
    return { id };
  }
});
/**
 * Set the batch number of a batch-tracked receipt line.
 *
 * @remarks
 * Creates or updates the line's batch (On Hold until the receipt posts) with
 * the line's quantity, its properties and an optional `expirationDate` in
 * `properties`. `trackedEntityId` names the line's existing batch (another
 * entity is refused); without it the batch already tagged with the line is
 * updated, so renaming a batch number never orphans the old one. Only a
 * Draft receipt's batches change.
 *
 * @mcp
 */
export const setReceiptLineBatch = defineServiceFn({
  input: z.object({
    receiptId: z.string(),
    receiptLineId: z.string(),
    batchNumber: z.string(),
    quantity: z.number(),
    properties: z.record(z.string(), z.unknown()).default({}),
    trackedEntityId: z.string().optional()
  }),
  permission: { create: "inventory" },

  async run(ctx, input) {
    const [line, receipt] = await Promise.all([
      service.receiptLineOf(ctx, input),
      ctx.asSystem.supabase
        .from("receipt")
        .select("status")
        .eq("id", input.receiptId)
        .eq("companyId", ctx.company.id)
        .maybeSingle()
    ]);
    if (line instanceof Error) return line;
    if (receipt.error) {
      return ctx.error("internal", "Failed to load receipt", receipt.error);
    }
    if (receipt.data?.status !== "Draft") {
      return ctx.error("rule", RECEIPT_LOCKED);
    }

    let trackedEntityId = input.trackedEntityId;
    if (trackedEntityId) {
      // The RPC rewrites this entity's quantity, status and attributes with
      // no ledger entry: it must be this line's own batch.
      const entity = await ctx.asSystem.supabase
        .from("trackedEntity")
        .select("id, attributes")
        .eq("id", trackedEntityId)
        .eq("companyId", ctx.company.id)
        .maybeSingle();
      if (entity.error || !entity.data) {
        return ctx.error("notFound", "The tracked entity could not be found");
      }
      const attributes = (entity.data.attributes ?? {}) as Record<
        string,
        unknown
      >;
      if (attributes["Receipt Line"] !== input.receiptLineId) {
        return ctx.error(
          "validation",
          "The tracked entity is not this receipt line's batch"
        );
      }
    } else {
      const existing = await ctx.asCaller.supabase
        .from("trackedEntity")
        .select("id")
        .eq("attributes ->> Receipt Line", input.receiptLineId)
        .eq("companyId", ctx.company.id)
        .maybeSingle();
      if (existing.error) {
        return ctx.error(
          "internal",
          "Failed to query batch number",
          existing.error
        );
      }
      trackedEntityId = existing.data?.id;
    }

    const updated = await ctx.asSystem.supabase.rpc(
      "update_receipt_line_batch_tracking",
      {
        p_tracked_entity_id: trackedEntityId,
        p_receipt_line_id: input.receiptLineId,
        p_receipt_id: input.receiptId,
        p_batch_number: input.batchNumber,
        p_quantity: input.quantity,
        p_properties: input.properties as Json
      }
    );
    if (updated.error) {
      return ctx.error("internal", "Failed to update tracking", updated.error);
    }
    return { receiptLineId: input.receiptLineId };
  }
});

/**
 * Set one serial number of a serial-tracked receipt line.
 *
 * @remarks
 * `index` is the unit's position on the line, from 0. An empty serial number
 * clears the position. A serial number the line's item already uses at another
 * position, or that belongs to an existing unit with stock movements, is
 * refused and the position is cleared.
 *
 * @mcp
 */
export const setReceiptLineSerial = defineServiceFn({
  input: z.object({
    receiptId: z.string(),
    receiptLineId: z.string(),
    serialNumber: z.string(),
    index: z.number().int().min(0),
    expiryDate: z.string().optional()
  }),
  permission: { create: "inventory" },

  async run(ctx, input) {
    const line = await service.receiptLineOf(ctx, input);
    if (line instanceof Error) return line;

    const box = {
      companyId: ctx.company.id,
      receiptLineId: input.receiptLineId,
      index: input.index
    };
    let saved: service.ReceiptSerialBoxResult;
    try {
      saved = await service.saveReceiptSerialBox(ctx.asSystem.pg, {
        ...box,
        receiptId: input.receiptId,
        itemId: line.itemId ?? "",
        serialNumber: input.serialNumber.trim(),
        expiryDate: input.expiryDate
      });
    } catch (error) {
      // The position shows a value that did not save; empty it so its
      // previous serial cannot post in its place.
      await service
        .clearReceiptSerialBox(ctx.asSystem.pg, box)
        .catch((clearError) =>
          logger.error("Failed to clear the serial box", {
            ...box,
            error: clearError
          })
        );
      if (isUniqueViolation(error)) {
        return ctx.error(
          "conflict",
          "Serial number already exists for this item"
        );
      }
      return ctx.error("internal", "Failed to update tracking", error);
    }

    if (!saved.ok) {
      switch (saved.reason) {
        case "notFound":
          return ctx.error("notFound", RECEIPT_NOT_FOUND);
        case "locked":
          return ctx.error("rule", RECEIPT_LOCKED);
        case "unit":
          return ctx.error(
            "conflict",
            "Serial number already belongs to an existing unit"
          );
        case "box":
          return ctx.error(
            "conflict",
            "Serial number is already used for a different item or position"
          );
      }
    }
    return { receiptLineId: input.receiptLineId, index: input.index };
  }
});
/**
 * Assign a returned tracked entity to a sales-return receipt line.
 *
 * @remarks
 * Re-tags the EXISTING entity a customer sent back with this receipt line,
 * instead of creating a new serial or batch; posting reactivates it On Hold.
 * The entity must be Consumed, the return line's item, and have left on a
 * posted shipment to the return's customer. One that another Draft
 * sales-return receipt has claimed is refused. Whatever entity held the slot
 * (`index` for a serial, the line for a batch) is cleared first.
 *
 * @mcp
 */
export const assignReceiptReturnEntity = defineServiceFn({
  input: z.object({
    receiptId: z.string(),
    receiptLineId: z.string(),
    trackedEntityId: z.string(),
    index: z.number().int().min(0).optional()
  }),
  permission: { create: "inventory" },

  async run(ctx, { receiptId, receiptLineId, trackedEntityId, index }) {
    const client = ctx.asCaller.supabase;
    const companyId = ctx.company.id;

    const [returnLine, entity, receipt] = await Promise.all([
      service.returnReceiptLineOf(ctx, { receiptId, receiptLineId }),
      client
        .from("trackedEntity")
        .select("id, status, attributes, itemId")
        .eq("id", trackedEntityId)
        .eq("companyId", companyId)
        .maybeSingle(),
      client
        .from("receipt")
        .select("status")
        .eq("id", receiptId)
        .eq("companyId", companyId)
        .maybeSingle()
    ]);
    if (returnLine instanceof Error) return returnLine;
    if (receipt.data?.status !== "Draft") {
      return ctx.error("rule", RECEIPT_LOCKED);
    }
    if (!entity.data) {
      return ctx.error("validation", "Tracked entity not found");
    }
    if (entity.data.status !== "Consumed") {
      return ctx.error(
        "rule",
        "Only shipped (consumed) entities can be returned"
      );
    }

    // "Which serial is it" lives on the receipt: the return order does not
    // pre-pick serials. The proof is provenance: the return line's item, and
    // left on a posted shipment to this return's customer.
    const orderLine = await client
      .from("salesReturnOrderLine")
      .select("itemId, salesReturnOrderId")
      .eq("id", returnLine.returnLineId)
      .eq("companyId", companyId)
      .maybeSingle();
    if (
      !orderLine.data ||
      orderLine.data.salesReturnOrderId !== returnLine.returnOrderId
    ) {
      return ctx.error(
        "validation",
        "Return line does not belong to this receipt's return order"
      );
    }
    if (entity.data.itemId !== orderLine.data.itemId) {
      return ctx.error(
        "validation",
        "Entity is a different item than this return line"
      );
    }

    const attributes = (entity.data.attributes ?? {}) as Record<
      string,
      unknown
    >;
    const returnOrder = await client
      .from("salesReturnOrder")
      .select("customerId")
      .eq("id", orderLine.data.salesReturnOrderId)
      .eq("companyId", companyId)
      .maybeSingle();
    const shipmentId = attributes.Shipment;
    const shippedToCustomer =
      returnOrder.data?.customerId && typeof shipmentId === "string"
        ? await client
            .from("shipment")
            .select("id")
            .eq("id", shipmentId)
            .eq("companyId", companyId)
            .eq("customerId", returnOrder.data.customerId)
            .eq("status", "Posted")
            .maybeSingle()
        : { data: null };
    if (!shippedToCustomer.data) {
      return ctx.error("rule", "Entity was not shipped to this customer");
    }

    // Overwriting another OPEN return receipt's claim would strip a validated
    // assignment off it. A Consumed entity still carrying its original
    // purchase receipt's attributes is fine.
    const claimedLine = attributes["Receipt Line"];
    if (typeof claimedLine === "string" && claimedLine !== receiptLineId) {
      const otherLine = await client
        .from("receiptLine")
        .select("receiptId")
        .eq("id", claimedLine)
        .eq("companyId", companyId)
        .maybeSingle();
      const otherReceipt = otherLine.data?.receiptId
        ? await client
            .from("receipt")
            .select("id, receiptId, sourceDocument, status")
            .eq("id", otherLine.data.receiptId)
            .eq("companyId", companyId)
            .maybeSingle()
        : { data: null };
      if (
        otherReceipt.data &&
        otherReceipt.data.id !== receiptId &&
        otherReceipt.data.sourceDocument === "Sales Return Order" &&
        otherReceipt.data.status === "Draft"
      ) {
        return ctx.error(
          "conflict",
          `Entity is already assigned on receipt ${otherReceipt.data.receiptId}. Remove it there first.`
        );
      }
    }

    const serviceRole = ctx.asSystem.supabase;
    // Clear the slot on any other entity occupying it.
    const stale = await client
      .from("trackedEntity")
      .select("id, attributes")
      .eq("attributes ->> Receipt Line", receiptLineId)
      .eq("companyId", companyId)
      .neq("id", trackedEntityId);
    for (const staleEntity of stale.data ?? []) {
      const staleAttributes = (staleEntity.attributes ?? {}) as Record<
        string,
        unknown
      >;
      const staleIndex = staleAttributes["Receipt Line Index"];
      if (index != null && staleIndex !== index && staleIndex !== undefined) {
        continue;
      }
      await serviceRole
        .from("trackedEntity")
        .update({
          attributes: service.withoutReceiptTracking(staleAttributes) as Json
        })
        .eq("id", staleEntity.id)
        .eq("companyId", companyId);
    }

    const assigned = await serviceRole
      .from("trackedEntity")
      .update({
        attributes: {
          ...service.withoutReceiptTracking(attributes),
          Receipt: receiptId,
          "Receipt Line": receiptLineId,
          ...(index != null ? { "Receipt Line Index": index } : {})
        } as Json
      })
      .eq("id", trackedEntityId)
      .eq("companyId", companyId);
    if (assigned.error) {
      return ctx.error("internal", "Failed to update tracking", assigned.error);
    }
    return { trackedEntityId };
  }
});

/**
 * Remove a returned tracked entity from a sales-return receipt line.
 *
 * @remarks
 * Clears the receipt tracking the entity carries, only when it points at
 * this receipt line: another receipt's assignment is refused.
 *
 * @mcp
 */
export const removeReceiptReturnEntity = defineServiceFn({
  input: z.object({
    receiptId: z.string(),
    receiptLineId: z.string(),
    trackedEntityId: z.string()
  }),
  permission: { create: "inventory" },

  async run(ctx, { receiptId, receiptLineId, trackedEntityId }) {
    const [returnLine, entity, receipt] = await Promise.all([
      service.returnReceiptLineOf(ctx, { receiptId, receiptLineId }),
      ctx.asCaller.supabase
        .from("trackedEntity")
        .select("id, attributes")
        .eq("id", trackedEntityId)
        .eq("companyId", ctx.company.id)
        .maybeSingle(),
      ctx.asCaller.supabase
        .from("receipt")
        .select("status")
        .eq("id", receiptId)
        .eq("companyId", ctx.company.id)
        .maybeSingle()
    ]);
    if (returnLine instanceof Error) return returnLine;
    if (receipt.data?.status !== "Draft") {
      return ctx.error("rule", RECEIPT_LOCKED);
    }
    if (!entity.data) {
      return ctx.error("validation", "Tracked entity not found");
    }

    const attributes = (entity.data.attributes ?? {}) as Record<
      string,
      unknown
    >;
    if (attributes["Receipt Line"] !== receiptLineId) {
      return ctx.error("rule", "Entity is not assigned to this receipt line");
    }

    const cleared = await ctx.asSystem.supabase
      .from("trackedEntity")
      .update({
        attributes: service.withoutReceiptTracking(attributes) as Json
      })
      .eq("id", trackedEntityId)
      .eq("companyId", ctx.company.id);
    if (cleared.error) {
      return ctx.error("internal", "Failed to update tracking", cleared.error);
    }
    return { trackedEntityId };
  }
});

// ---------------------------------------------------------------------------
// Shipments
// ---------------------------------------------------------------------------

const SHIPMENT_NOT_FOUND = "Shipment not found";
const SHIPMENT_LOCKED = "A posted shipment can no longer be changed";
const NO_DEFAULT_LOCATION =
  "Set a default location in your settings before creating a shipment";

type ExpiredEntityPolicy = "Warn" | "Block" | "BlockWithOverride";

/**
 * Create a shipment.
 *
 * @remarks
 * From its source document, with its lines: a sales order, a sales return
 * order, a purchase order, a purchase return order, an outbound warehouse
 * transfer or a rental agreement. With no source document it creates an
 * empty shipment. The location is the caller's default location, which a
 * purchase order shipment requires. A sales order shipment ships from the
 * order's location, or from the caller's default location when one of the
 * order's lines ships from there.
 *
 * A return order or rental agreement with a Draft shipment already returns
 * that shipment instead of a second one.
 *
 * @mcp
 */
export const createShipment = defineServiceFn({
  input: z.object({
    sourceDocument: z.enum(shipmentSourceDocumentType).optional(),
    sourceDocumentId: z.string().default("")
  }),
  permission: { create: "inventory" },

  async run(ctx, { sourceDocument, sourceDocumentId }) {
    let locationId = await service.defaultLocationOf(ctx);
    if (sourceDocument === "Sales Order") {
      const location = await service.salesOrderShipmentLocationOf(
        ctx,
        sourceDocumentId,
        locationId
      );
      if (location.error) {
        return ctx.error(
          "internal",
          "Failed to load the sales order's location",
          location.error
        );
      }
      locationId = location.data ?? undefined;
    }

    if (
      !locationId &&
      (sourceDocument === "Sales Order" || sourceDocument === "Purchase Order")
    ) {
      return ctx.error("rule", NO_DEFAULT_LOCATION);
    }

    // One open draft per return order or agreement: a second Ship goes to
    // the existing draft instead of stacking up duplicates.
    if (
      sourceDocument === "Sales Return Order" ||
      sourceDocument === "Purchase Return Order" ||
      sourceDocument === "Rental Agreement"
    ) {
      const existing = await ctx.asCaller.supabase
        .from("shipment")
        .select("id")
        .eq("sourceDocument", sourceDocument)
        .eq("sourceDocumentId", sourceDocumentId)
        .eq("status", "Draft")
        .eq("companyId", ctx.company.id)
        .order("createdAt", { ascending: false })
        .limit(1)
        .maybeSingle();
      if (existing.error) {
        return ctx.error(
          "internal",
          "Failed to check for an existing shipment",
          existing.error
        );
      }
      if (existing.data) return { id: existing.data.id };
    }

    const created = await (() => {
      switch (sourceDocument) {
        case "Sales Order":
          return invokeCreate(ctx, {
            type: "shipmentFromSalesOrder",
            locationId: locationId!,
            salesOrderId: sourceDocumentId,
            shipmentId: undefined
          });
        case "Sales Return Order":
          return invokeCreate(ctx, {
            type: "shipmentFromSalesReturnOrder",
            locationId,
            salesReturnOrderId: sourceDocumentId,
            shipmentId: undefined
          });
        case "Purchase Return Order":
          return invokeCreate(ctx, {
            type: "shipmentFromPurchaseReturnOrder",
            locationId,
            purchaseReturnOrderId: sourceDocumentId,
            shipmentId: undefined
          });
        case "Purchase Order":
          return invokeCreate(ctx, {
            type: "shipmentFromPurchaseOrder",
            locationId: locationId!,
            purchaseOrderId: sourceDocumentId,
            shipmentId: undefined
          });
        case "Outbound Transfer":
          return invokeCreate(ctx, {
            type: "shipmentFromWarehouseTransfer",
            warehouseTransferId: sourceDocumentId,
            shipmentId: undefined
          });
        case "Rental Agreement":
          return invokeCreate(ctx, {
            type: "shipmentFromRentalAgreement",
            rentalAgreementId: sourceDocumentId
          });
        default:
          return invokeCreate(ctx, {
            type: "shipmentDefault",
            locationId
          });
      }
    })();
    if (created.error || !created.data) {
      return service.serverFnFailure(
        ctx,
        created.error,
        getErrorMessage(created.error, "Failed to create shipment")
      );
    }
    return { id: created.data.id };
  }
});

/**
 * Update a shipment's details.
 *
 * @remarks
 * A changed source document or location rebuilds the shipment's lines from
 * the new source (a sales order, a sales return order, a purchase order, a
 * purchase return order or an outbound transfer), and is refused once the
 * shipment is not Draft. Otherwise the fields are saved as sent. A rental
 * shipment keeps its rental agreement: changing it is refused.
 *
 * @mcp
 */
export const updateShipment = defineServiceFn({
  input: z.object({
    id: z.string(),
    shipmentId: z.string().min(1),
    locationId: z.string().optional(),
    sourceDocument: z.enum(shipmentSourceDocumentType).optional(),
    sourceDocumentId: z.string().min(1),
    trackingNumber: z.string().optional(),
    shippingMethodId: z.string().optional(),
    sourceDocumentReadableId: z.string().optional(),
    customerId: z.string().optional(),
    customFields: customFieldsInput
  }),
  permission: { update: "inventory" },

  async run(ctx, { id, ...shipment }) {
    const current = await ctx.asCaller.supabase
      .from("shipment")
      .select("sourceDocument, sourceDocumentId, locationId, status")
      .eq("id", id)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (current.error) {
      return ctx.error("internal", "Failed to load shipment", current.error);
    }
    if (!current.data) return ctx.error("notFound", SHIPMENT_NOT_FOUND);

    const sourceChanged =
      current.data.sourceDocument !== shipment.sourceDocument ||
      current.data.sourceDocumentId !== shipment.sourceDocumentId;
    const isRental =
      current.data.sourceDocument === "Rental Agreement" ||
      shipment.sourceDocument === "Rental Agreement";
    if (isRental && sourceChanged) {
      return ctx.error(
        "rule",
        "A rental shipment keeps its rental agreement. Create it from the agreement."
      );
    }

    const rebuild =
      !isRental &&
      (sourceChanged || current.data.locationId !== shipment.locationId);
    // A rebuild replaces the lines: on a posted shipment, the posted ones.
    if (rebuild && current.data.status !== "Draft") {
      return ctx.error(
        "rule",
        "Only a Draft shipment can change its source document or location"
      );
    }
    if (!rebuild) {
      const updated = await service.upsertShipment(ctx.asCaller.supabase, {
        id,
        ...shipment,
        updatedBy: ctx.auditUserId
      });
      if (updated.error) {
        return ctx.error(
          "internal",
          "Failed to update shipment",
          updated.error
        );
      }
      return { id };
    }

    const { locationId, sourceDocumentId } = shipment;
    const created = await (() => {
      switch (shipment.sourceDocument) {
        case "Sales Order":
          return invokeCreate(ctx, {
            type: "shipmentFromSalesOrder",
            locationId: locationId as string,
            salesOrderId: sourceDocumentId,
            shipmentId: id
          });
        case "Sales Return Order":
          return invokeCreate(ctx, {
            type: "shipmentFromSalesReturnOrder",
            locationId,
            salesReturnOrderId: sourceDocumentId,
            shipmentId: id
          });
        case "Purchase Return Order":
          return invokeCreate(ctx, {
            type: "shipmentFromPurchaseReturnOrder",
            locationId,
            purchaseReturnOrderId: sourceDocumentId,
            shipmentId: id
          });
        case "Purchase Order":
          return invokeCreate(ctx, {
            type: "shipmentFromPurchaseOrder",
            locationId: locationId as string,
            purchaseOrderId: sourceDocumentId,
            shipmentId: id
          });
        case "Outbound Transfer":
          return invokeCreate(ctx, {
            type: "shipmentFromWarehouseTransfer",
            warehouseTransferId: sourceDocumentId,
            shipmentId: id
          });
        default:
          return null;
      }
    })();
    if (!created) {
      return ctx.error(
        "validation",
        `Unsupported source document: ${shipment.sourceDocument}`
      );
    }
    if (created.error || !created.data) {
      return service.serverFnFailure(
        ctx,
        created.error,
        getErrorMessage(created.error, "Failed to create shipment")
      );
    }
    return { id };
  }
});
/**
 * Post a shipment.
 *
 * @remarks
 * In order:
 *   1. Storage rules run on the `shipment` and `pick` surfaces (and
 *      `warehouseTransfer` for an outbound transfer), and a sales order
 *      shipment runs its order's sales rules on the lines shipped. A
 *      blocking rule returns its `violations` and `ruleNames` and changes
 *      nothing (a blocked sales rule is recorded on the order); send
 *      `acknowledged: true` to post past warnings.
 *   2. Expired batches on the shipment: the company's expired-entity policy
 *      refuses the post (`Block`, `BlockWithOverride`), or posts it with a
 *      `warning` (`Warn`). Expiry is judged on the shipping location's
 *      calendar.
 *   3. The shipment is set Pending (only from Draft or Pending: `conflict`
 *      otherwise). A sales order shipment saves its packing slip on the
 *      order's opportunity.
 *   4. The shipment is posted: ledger entries, cost of goods, the journal and
 *      tracked entities. A failed post sets it back to Draft.
 *   5. Labels print when the shipping printer auto-prints (and for batches
 *      the post split), acknowledged sales rules are recorded on the order,
 *      and the shipment-posted workflow moment is raised.
 *
 * `postingDate` dates a rental delivery; every other shipment posts today.
 * `locale` formats the packing slip.
 *
 * @mcp
 */
export const postShipment = defineServiceFn({
  input: z.object({
    shipmentId: z.string(),
    acknowledged: z.boolean().default(false),
    postingDate: z.string().optional(),
    locale: z.string().default("en-US")
  }),
  permission: { update: "inventory" },

  async run(ctx, { shipmentId, acknowledged, postingDate, locale }) {
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;
    const serviceRole = ctx.asSystem.supabase;

    const [lines, shipment] = await Promise.all([
      serviceRole
        .from("shipmentLine")
        .select(
          "id, lineId, itemId, storageUnitId, shippedQuantity, locationId, shipmentId"
        )
        .eq("shipmentId", shipmentId)
        .eq("companyId", companyId),
      serviceRole
        .from("shipment")
        .select("sourceDocument, sourceDocumentId, locationId")
        .eq("id", shipmentId)
        .eq("companyId", companyId)
        .maybeSingle()
    ]);
    // Everything below reads as the system by shipment id, so a shipment
    // outside this company stops here.
    if (!shipment.data) {
      logger.error("Shipment not found for company", { companyId, shipmentId });
      return ctx.error("notFound", SHIPMENT_NOT_FOUND);
    }

    const isTransfer = shipment.data.sourceDocument === "Outbound Transfer";
    const rules = await service.storageRuleViolations(
      ctx,
      isTransfer
        ? ["shipment", "warehouseTransfer", "pick", "warehouseTransfer"]
        : ["shipment", "pick"],
      (lines.data ?? []).map((line) => ({
        lineId: line.id,
        itemId: line.itemId,
        storageUnitId: line.storageUnitId,
        quantity: Number(line.shippedQuantity ?? 0),
        locationId: line.locationId
      }))
    );

    // Sales rules have no shipment surface: the order's lines are evaluated
    // as `salesOrderLine`, at THIS shipment's quantities (an unshipped
    // violating line must not block a partial shipment of a clean one), for
    // the order's resolved ship-to.
    const salesOrderId =
      shipment.data.sourceDocument === "Sales Order"
        ? shipment.data.sourceDocumentId
        : null;
    let salesViolations: Violation[] = [];
    if (salesOrderId) {
      const shipTo = await resolveSalesOrderShipTo(
        serviceRole,
        salesOrderId,
        companyId
      );
      const sales = await evaluateSalesRuleLines({
        client: serviceRole,
        companyId,
        userId,
        surface: "salesOrderLine",
        lines: (lines.data ?? [])
          .filter((line) => !!line.itemId && Number(line.shippedQuantity) > 0)
          .map((line) => ({
            // The order line, when linked, so the evidence lands on it.
            lineId: line.lineId ?? line.id,
            itemId: line.itemId as string,
            quantity: Number(line.shippedQuantity)
          })),
        customerId: shipTo.customerId,
        customerLocationId: shipTo.customerLocationId
      });
      salesViolations = dedupeViolations(sales.violations);
      rules.violations.push(...sales.violations);
      Object.assign(rules.ruleNames, sales.ruleNames);
    }

    // Evidence covers the SALES violations only, attributed to the order. A
    // post blocked by any violation records its sales violations as blocked;
    // acknowledged ones wait until the post has committed.
    const violations = dedupeViolations(rules.violations);
    if (violations.length > 0 && isBlocked(violations, acknowledged)) {
      if (salesViolations.length > 0 && salesOrderId) {
        await recordSalesRuleOutcome(serviceRole, {
          companyId,
          userId,
          documentType: "salesOrder",
          documentId: salesOrderId,
          outcome: "blocked",
          violations: salesViolations,
          ruleNames: rules.ruleNames
        });
      }
      return { violations, ruleNames: rules.ruleNames } satisfies Blocked;
    }

    // Expired batches, as post-stock-transfer and issue judge them.
    const [settings, entities] = await Promise.all([
      serviceRole
        .from("companySettings")
        .select("inventoryShelfLife")
        .eq("id", companyId)
        .single(),
      serviceRole
        .from("trackedEntity")
        .select("id, readableId, expirationDate")
        .eq("attributes ->> Shipment", shipmentId)
        .eq("companyId", companyId)
    ]);
    const policy: ExpiredEntityPolicy =
      (
        settings.data?.inventoryShelfLife as {
          expiredEntityPolicy?: ExpiredEntityPolicy;
        } | null
      )?.expiredEntityPolicy ?? "Block";
    // The shipping site's calendar: a lot that expires today must not read
    // as expired at a plant still on yesterday.
    const today = datetime.today(
      shipment.data.locationId
        ? await getLocationTimeZone(
            serviceRole,
            shipment.data.locationId,
            companyId
          )
        : await getCompanyTimeZone(serviceRole, companyId)
    );
    const expired = (entities.data ?? []).filter((entity) => {
      if (!entity.expirationDate) return false;
      try {
        return parseDate(entity.expirationDate).compare(today) < 0;
      } catch {
        return false;
      }
    });
    let warning: string | null = null;
    if (expired.length > 0) {
      const ids = expired.map((e) => e.readableId ?? e.id).join(", ");
      const batches = expired.length === 1 ? "batch" : "batches";
      if (policy === "Block" || policy === "BlockWithOverride") {
        return ctx.error(
          "rule",
          `Cannot post shipment with expired ${batches}: ${ids}`
        );
      }
      warning = `Posted shipment with expired ${batches}: ${ids}`;
    }

    const pending = await ctx.asCaller.supabase
      .from("shipment")
      .update({ status: "Pending" })
      .eq("id", shipmentId)
      .eq("companyId", companyId)
      .in("status", ["Draft", "Pending"])
      .select("id");
    if (pending.error) {
      return ctx.error("internal", "Failed to post shipment", pending.error);
    }
    if (!pending.data?.length) {
      return ctx.error(
        "conflict",
        "This shipment has already been posted or voided"
      );
    }

    // Only from Pending: a concurrent post that won must stay Posted.
    const backToDraft = () =>
      ctx.asCaller.supabase
        .from("shipment")
        .update({ status: "Draft" })
        .eq("id", shipmentId)
        .eq("companyId", companyId)
        .eq("status", "Pending");

    let failure: CarbonError | null = null;
    let splitEntityIds: string[] = [];
    try {
      await service.savePackingSlip(ctx, { shipmentId, locale });
      const posted = await invokePosting(
        ctx,
        "post-shipment",
        {
          type: "post",
          shipmentId,
          postingDate
        },
        service.postShipment
      );
      if (posted.error) {
        await backToDraft();
        return service.serverFnFailure(
          ctx,
          posted.error,
          "Failed to post shipment"
        );
      }
      splitEntityIds = posted.data?.splitEntityIds ?? [];
    } catch (thrown) {
      await backToDraft();
      failure = ctx.error("internal", "Failed to post shipment", thrown);
    }

    if (!failure) {
      await service.autoPrint(ctx, {
        sourceDocument: "Shipment",
        sourceDocumentId: shipmentId,
        locationId: shipment.data.locationId,
        context: "shipping"
      });
      // The RETAINED shelf lots of a batch split are reprinted: their
      // quantity changed. The shipped child left Consumed and gets no label.
      await service.printEntityLabels(ctx, splitEntityIds);
    }

    // Raised after a rollback to Draft too: when workflows fire is its own
    // decision (#1294), unchanged here.
    await raiseMoment("inventory.shipmentPosted", {
      outputs: { shipment: { id: shipmentId }, postedBy: { id: userId } },
      companyId,
      actorId: userId
    });

    if (failure) return failure;
    // Acknowledged-override evidence only once the post has stuck.
    if (salesViolations.length > 0 && salesOrderId) {
      await recordSalesRuleOutcome(serviceRole, {
        companyId,
        userId,
        documentType: "salesOrder",
        documentId: salesOrderId,
        outcome: "acknowledged",
        violations: salesViolations,
        ruleNames: rules.ruleNames
      });
    }
    trackWorkEvent("shipment_posted", {
      companyId,
      userId,
      shipmentId,
      sourceDocument: shipment.data.sourceDocument ?? null
    });
    return { warning };
  }
});

/**
 * Void a posted shipment.
 *
 * @remarks
 * Reverses its inventory movements and journal entries and restores its
 * tracked entities and the source document's shipped quantities. Only a
 * Posted shipment can be voided.
 *
 * @mcp destructive
 */
export const voidShipment = defineServiceFn({
  input: z.object({ shipmentId: z.string() }),
  permission: { update: "inventory" },

  async run(ctx, { shipmentId }) {
    const shipment = await ctx.asCaller.supabase
      .from("shipment")
      .select("status")
      .eq("id", shipmentId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (shipment.error) {
      return ctx.error("internal", "Failed to void shipment", shipment.error);
    }
    if (!shipment.data) return ctx.error("notFound", SHIPMENT_NOT_FOUND);
    if (shipment.data.status !== "Posted") {
      return ctx.error("rule", "Can only void posted shipments");
    }

    const voided = await invokePosting(
      ctx,
      "post-shipment",
      {
        type: "void",
        shipmentId
      },
      service.postShipment
    );
    if (voided.error) {
      return service.serverFnFailure(
        ctx,
        voided.error,
        "Failed to void shipment"
      );
    }
    return { shipmentId };
  }
});

/**
 * Split a shipment line in two.
 *
 * @remarks
 * Moves `quantity` of the line onto a new line of the same shipment, so the
 * two can come from different storage units or carry different tracking.
 *
 * @mcp
 */
export const splitShipmentLine = defineServiceFn({
  input: z.object({
    shipmentId: z.string().min(1),
    shipmentLineId: z.string().min(1),
    locationId: z.string().min(1),
    quantity: z.number()
  }),
  permission: { update: "inventory" },

  async run(ctx, { shipmentId, shipmentLineId, locationId, quantity }) {
    const line = await ctx.asCaller.supabase
      .from("shipmentLine")
      .select("id, shipment!shipmentLine_shipmentId_fkey(status)")
      .eq("id", shipmentLineId)
      .eq("shipmentId", shipmentId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (line.error) {
      return ctx.error("internal", "Failed to split line", line.error);
    }
    if (!line.data?.shipment) {
      return ctx.error("notFound", "The shipment line could not be found");
    }
    if (line.data.shipment.status !== "Draft") {
      return ctx.error("rule", SHIPMENT_LOCKED);
    }

    const split = await invokeCreate(ctx, {
      type: "shipmentLineSplit",
      locationId,
      shipmentId,
      shipmentLineId,
      quantity
    });
    if (split.error) {
      return service.serverFnFailure(ctx, split.error, "Failed to split line");
    }
    return { shipmentLineId };
  }
});

/**
 * Set one field on shipment lines.
 *
 * @remarks
 * `storageUnitId` or `shippedQuantity`, on every line in `ids`. An empty
 * value clears the field. Storage rules run when the shipment is posted, not
 * here.
 *
 * @mcp
 */
export const updateShipmentLines = defineServiceFn({
  input: z.object({
    ids: z.array(z.string()).min(1),
    field: z.enum(["storageUnitId", "shippedQuantity"]),
    value: z.string().nullable()
  }),
  permission: { update: "inventory" },

  async run(ctx, { ids, field, value }) {
    const lines = await ctx.asCaller.supabase
      .from("shipmentLine")
      .select("id, shipment!shipmentLine_shipmentId_fkey(status)")
      .in("id", ids)
      .eq("companyId", ctx.company.id);
    if (lines.error) {
      return ctx.error(
        "internal",
        "Failed to load shipment lines",
        lines.error
      );
    }
    if (lines.data.length !== new Set(ids).size) {
      return ctx.error("notFound", "The shipment line could not be found");
    }
    if (lines.data.some((line) => line.shipment?.status !== "Draft")) {
      return ctx.error("rule", SHIPMENT_LOCKED);
    }

    const update = await ctx.asCaller.supabase
      .from("shipmentLine")
      .update({
        ...(field === "storageUnitId"
          ? { storageUnitId: value || null }
          : { shippedQuantity: Number(value || 0) }),
        updatedBy: ctx.auditUserId,
        updatedAt: datetime.timestamp()
      })
      .in("id", ids)
      .eq("companyId", ctx.company.id);
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update shipment lines",
        update.error
      );
    }
    return { ids };
  }
});

/**
 * Update one field of a fixed-asset line on a shipment.
 *
 * @remarks
 * `shipped`, `serialNumber` or `meter` (a rental unit's meter out). A posted
 * or voided shipment is a record: its lines no longer change.
 *
 * @mcp
 */
export const updateShipmentFixedAssetLine = defineServiceFn({
  input: shipmentFixedAssetLineUpdateValidator,
  permission: { update: "inventory" },

  async run(ctx, { id, ...change }) {
    const serviceRole = ctx.asSystem.supabase;
    const line = await serviceRole
      .from("shipmentFixedAssetLine")
      .select("shipment!shipmentFixedAssetLine_shipmentId_fkey(status)")
      .eq("id", id)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (line.error || !line.data?.shipment) {
      return ctx.error("notFound", "The shipment line could not be found");
    }
    if (line.data.shipment.status !== "Draft") {
      return ctx.error("rule", "A posted shipment can no longer be changed");
    }

    const update = await serviceRole
      .from("shipmentFixedAssetLine")
      .update({
        ...(change.field === "shipped"
          ? { shipped: change.value }
          : change.field === "serialNumber"
            ? { serialNumber: change.value || null }
            : { meter: change.value === "" ? null : Number(change.value) }),
        updatedBy: ctx.auditUserId
      })
      .eq("id", id)
      .eq("companyId", ctx.company.id);
    if (update.error) {
      return ctx.error("internal", "Failed to update the line", update.error);
    }
    return { id };
  }
});

/**
 * Assign a tracked entity to a shipment line.
 *
 * @remarks
 * Tags the batch, or the serial unit at `index`, with the shipment line;
 * posting ships it. The entity must be the line's item and Available (On
 * Hold for a return-to-customer shipment, and then it must have come back on
 * a receipt of that return order). A batch must hold at least `quantity`.
 * Whatever entity held the slot before is cleared once the new one is set.
 *
 * @mcp
 */
export const assignShipmentLineEntity = defineServiceFn({
  input: z.discriminatedUnion("trackingType", [
    z.object({
      trackingType: z.literal("batch"),
      shipmentId: z.string(),
      shipmentLineId: z.string(),
      trackedEntityId: z.string(),
      quantity: z.number()
    }),
    z.object({
      trackingType: z.literal("serial"),
      shipmentId: z.string(),
      shipmentLineId: z.string(),
      trackedEntityId: z.string(),
      index: z.number().int().min(0)
    })
  ]),
  permission: { create: "inventory" },

  async run(ctx, input) {
    const { shipmentId, shipmentLineId, trackedEntityId } = input;
    const client = ctx.asCaller.supabase;
    const companyId = ctx.company.id;

    // The LINE's item, never the caller's, is what the entity must match.
    const [entity, shipment, line] = await Promise.all([
      client
        .from("trackedEntity")
        .select("*")
        .eq("id", trackedEntityId)
        .eq("companyId", companyId)
        .single(),
      client
        .from("shipment")
        .select("sourceDocument, sourceDocumentId, status, supplierId")
        .eq("id", shipmentId)
        .eq("companyId", companyId)
        .single(),
      client
        .from("shipmentLine")
        .select("itemId")
        .eq("id", shipmentLineId)
        .eq("shipmentId", shipmentId)
        .eq("companyId", companyId)
        .single()
    ]);
    if (entity.error) {
      return ctx.error("notFound", "Tracked entity not found", entity.error);
    }
    // A failed lookup must not fall back to "Available": that would refuse a
    // legitimate On Hold return-to-customer assignment.
    if (shipment.error) {
      return ctx.error("internal", "Failed to load shipment", shipment.error);
    }
    if (shipment.data.status !== "Draft") {
      return ctx.error("rule", SHIPMENT_LOCKED);
    }
    if (line.error) {
      return ctx.error("internal", "Failed to load shipment line", line.error);
    }
    if (
      entity.data.itemId &&
      line.data.itemId &&
      entity.data.itemId !== line.data.itemId
    ) {
      return ctx.error(
        "validation",
        "Tracked entity does not match the line's item"
      );
    }

    // The statuses this source may ship (`shippableEntityStatuses`): a
    // return-to-customer ships returned stock, On Hold until it is
    // dispositioned; a return-to-supplier also ships rejected units;
    // everything else ships Available stock only. On Hold alone is not
    // provenance: the entity must have COME BACK on a receipt of this
    // return order.
    const isReturn = shipment.data.sourceDocument === "Sales Return Order";
    const allowedStatuses = utils.shippableEntityStatuses(
      shipment.data.sourceDocument
    );
    const attributes = (entity.data.attributes ?? {}) as Record<
      string,
      unknown
    >;
    if (isReturn) {
      const receiptId = attributes.Receipt;
      const provenance =
        typeof receiptId === "string"
          ? await client
              .from("receipt")
              .select("id")
              .eq("id", receiptId)
              .eq("sourceDocument", "Sales Return Order")
              .eq("sourceDocumentId", shipment.data.sourceDocumentId ?? "")
              .eq("companyId", companyId)
              .maybeSingle()
          : { data: null, error: null };
      if (provenance.error) {
        return ctx.error(
          "internal",
          "Failed to verify the entity's provenance",
          provenance.error
        );
      }
      if (!provenance.data) {
        return ctx.error(
          "rule",
          "Tracked entity was not received on this return order and cannot ship back on it"
        );
      }
    }

    if (!allowedStatuses.includes(entity.data.status)) {
      return ctx.error(
        "rule",
        `Tracked entity is not available. Current status: ${entity.data.status}`
      );
    }

    // Rejected alone is not provenance either: a rejected unit goes back only
    // to the supplier it came from, i.e. it was received on a posted receipt
    // from this return's supplier (the rule the return-line picker applies).
    if (
      shipment.data.sourceDocument === "Purchase Return Order" &&
      entity.data.status === "Rejected"
    ) {
      const receiptId = attributes.Receipt;
      const provenance =
        typeof receiptId === "string" && shipment.data.supplierId
          ? await client
              .from("receipt")
              .select("id")
              .eq("id", receiptId)
              .eq("supplierId", shipment.data.supplierId)
              .eq("status", "Posted")
              .eq("companyId", companyId)
              .maybeSingle()
          : { data: null, error: null };
      if (provenance.error) {
        return ctx.error(
          "internal",
          "Failed to verify the entity's provenance",
          provenance.error
        );
      }
      if (!provenance.data) {
        return ctx.error(
          "rule",
          "Rejected tracked entity was not received from this supplier and cannot be returned to it"
        );
      }
    }

    // Rounded: a lot left holding 0.020000000000000018 by an earlier split
    // has enough for a 0.02 assignment.
    if (
      input.trackingType === "batch" &&
      round(entity.data.quantity) < round(input.quantity)
    ) {
      return ctx.error("rule", "Batch has insufficient quantity");
    }

    const serviceRole = ctx.asSystem.supabase;
    const updated = await serviceRole
      .from("trackedEntity")
      .update({
        attributes: {
          ...attributes,
          "Shipment Line": shipmentLineId,
          Shipment: shipmentId,
          ...(input.trackingType === "serial"
            ? { "Shipment Line Index": input.index }
            : {})
        } as Json
      })
      .eq("id", trackedEntityId)
      .eq("companyId", companyId)
      // Guards a concurrent status change: no row matched is a conflict.
      .eq("status", entity.data.status)
      .select("id");
    if (updated.error) {
      return ctx.error(
        "internal",
        "Failed to assign the tracked entity",
        updated.error
      );
    }
    if (!updated.data?.length) {
      return ctx.error(
        "conflict",
        `Tracked entity is no longer ${entity.data.status}`
      );
    }

    // Only now is the slot's previous entity cleared: for a batch any other
    // entity on the line, for a serial the one at this index.
    let staleQuery = serviceRole
      .from("trackedEntity")
      .select("id, attributes")
      .eq("companyId", companyId)
      .eq("attributes ->> Shipment Line", shipmentLineId)
      .neq("id", trackedEntityId);
    if (input.trackingType === "serial") {
      staleQuery = staleQuery.eq(
        "attributes ->> Shipment Line Index",
        String(input.index)
      );
    }
    const stale = await staleQuery;
    await Promise.all(
      (stale.data ?? []).map((row) => {
        const {
          "Shipment Line": _line,
          Shipment: _shipment,
          "Shipment Line Index": _index,
          ...cleaned
        } = (row.attributes ?? {}) as Record<string, unknown>;
        return serviceRole
          .from("trackedEntity")
          .update({ attributes: cleaned as Json })
          .eq("id", row.id)
          .eq("companyId", companyId);
      })
    );

    return { trackedEntityId };
  }
});

// ---------------------------------------------------------------------------
// Stock transfers
// ---------------------------------------------------------------------------

/**
 * Create a stock transfer.
 *
 * @remarks
 * Moves stock between storage units of one location. The transfer is created
 * Released, so storage rules run on the `stockTransfer` surface against each
 * line's destination before it exists: a blocking rule returns its
 * `violations` and `ruleNames` and creates nothing; send `acknowledged: true`
 * to create past warnings. A serial-tracked line of N units becomes N lines
 * of one.
 *
 * @mcp
 */
export const createStockTransfer = defineServiceFn({
  input: z.object({
    locationId: z.string().min(1),
    lines: z
      .array(
        z.object({
          itemId: z.string().min(1),
          fromStorageUnitId: z.string().nullish(),
          toStorageUnitId: z.string().nullish(),
          quantity: z.number().min(0).optional(),
          requiresSerialTracking: z.boolean().optional(),
          requiresBatchTracking: z.boolean().optional()
        })
      )
      .min(1),
    acknowledged: z.boolean().default(false),
    customFields: customFieldsInput
  }),
  permission: { create: "inventory" },

  async run(ctx, { locationId, lines, acknowledged, customFields }) {
    const rules = await service.storageRuleViolations(
      ctx,
      ["stockTransfer"],
      lines.map((line, i) => ({
        lineId: `pending-${i}`,
        itemId: line.itemId,
        storageUnitId: line.toStorageUnitId ?? null,
        quantity: Number(line.quantity ?? 0),
        locationId
      }))
    );
    if (
      rules.violations.length > 0 &&
      isBlocked(rules.violations, acknowledged)
    ) {
      return rules satisfies Blocked;
    }

    const created = await service.insertStockTransfer(ctx.asCaller.supabase, {
      locationId,
      lines,
      companyId: ctx.company.id,
      createdBy: ctx.auditUserId,
      customFields
    });
    if (created.error || !created.data) {
      return ctx.error(
        "internal",
        "Failed to create stock transfer",
        created.error
      );
    }
    return created.data;
  }
});

/**
 * Set a stock transfer's status.
 *
 * @remarks
 * Released and Completed commit the transfer plan: storage rules run on the
 * `stockTransfer` surface against each line's destination, and a blocking
 * rule returns its `violations` and `ruleNames` and changes nothing (send
 * `acknowledged: true` to continue past warnings). Reopening a Completed
 * transfer needs the inventory `delete` permission. Completing it clears the
 * assignee and stamps the completion time.
 *
 * @mcp
 */
export const setStockTransferStatus = defineServiceFn({
  input: z.object({
    id: z.string(),
    status: z.enum(stockTransferStatusType),
    acknowledged: z.boolean().default(false)
  }),
  permission: { update: "inventory" },

  async run(ctx, { id, status, acknowledged }) {
    const current = await ctx.asCaller.supabase
      .from("stockTransfer")
      .select("status")
      .eq("id", id)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (current.error) {
      return ctx.error(
        "internal",
        "Failed to load stock transfer",
        current.error
      );
    }
    if (!current.data) {
      return ctx.error("notFound", "The stock transfer could not be found");
    }
    // Reopening unlocks completed inventory moves.
    if (
      status !== "Completed" &&
      current.data.status === "Completed" &&
      !ctx.can({ delete: "inventory" })
    ) {
      return ctx.error(
        "forbidden",
        "Reopening a completed stock transfer needs the inventory delete permission"
      );
    }

    // Released is the commitment to the plan; Completed is kept as a second
    // gate. Draft is editing and In Progress is set by picking.
    if (status === "Released" || status === "Completed") {
      const lines = await ctx.asSystem.supabase
        .from("stockTransferLine")
        .select("id, itemId, toStorageUnitId, quantity")
        .eq("stockTransferId", id)
        .eq("companyId", ctx.company.id);
      const rules = await service.storageRuleViolations(
        ctx,
        ["stockTransfer"],
        (lines.data ?? []).map((line) => ({
          lineId: line.id,
          itemId: line.itemId,
          storageUnitId: line.toStorageUnitId,
          quantity: Number(line.quantity ?? 0),
          locationId: null
        }))
      );
      if (
        rules.violations.length > 0 &&
        isBlocked(rules.violations, acknowledged)
      ) {
        return rules satisfies Blocked;
      }
    }

    const completed = status === "Completed";
    const update = await service.updateStockTransferStatus(
      ctx.asCaller.supabase,
      {
        id,
        status,
        assignee: completed ? null : undefined,
        completedAt: completed ? datetime.timestamp() : null,
        updatedBy: ctx.auditUserId
      }
    );
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update stock transfer status",
        update.error
      );
    }
    return { id, status };
  }
});
/**
 * Pick a stock transfer line.
 *
 * @remarks
 * Moves `quantity` of the line's item from its source to its destination
 * storage unit. A serial- or batch-tracked line needs its `trackedEntityId`;
 * `pickStockTransferLineEntity` picks a scanned one. A Completed
 * transfer is refused.
 *
 * @mcp
 */
export const pickStockTransferLine = defineServiceFn({
  input: z.object({
    lineId: z.string(),
    quantity: z.number().positive(),
    locationId: z.string(),
    trackedEntityId: z.string().optional()
  }),
  permission: { create: "inventory" },

  async run(ctx, { lineId, quantity, locationId, trackedEntityId }) {
    const line = await service.stockTransferLineOf(ctx, lineId);
    if (line instanceof Error) return line;
    if (
      !trackedEntityId &&
      (line.requiresSerialTracking || line.requiresBatchTracking)
    ) {
      return ctx.error("validation", "Tracked entity not found");
    }
    return service.postStockTransferLine(
      ctx,
      {
        type: "inventory",
        stockTransferId: line.stockTransferId,
        stockTransferLineId: lineId,
        quantity,
        locationId,
        trackedEntityId
      },
      () => "Failed to pick line"
    );
  }
});

/**
 * Unpick a stock transfer line.
 *
 * @remarks
 * Moves the line's picked stock back to its source storage unit. A serial-
 * or batch-tracked line needs its `trackedEntityId`. A Completed transfer is
 * refused.
 *
 * @mcp
 */
export const unpickStockTransferLine = defineServiceFn({
  input: z.object({
    lineId: z.string(),
    locationId: z.string(),
    trackedEntityId: z.string().optional()
  }),
  permission: { create: "inventory" },

  async run(ctx, { lineId, locationId, trackedEntityId }) {
    const line = await service.stockTransferLineOf(ctx, lineId);
    if (line instanceof Error) return line;
    if (
      !trackedEntityId &&
      (line.requiresSerialTracking || line.requiresBatchTracking)
    ) {
      return ctx.error("validation", "Tracked entity not found");
    }
    return service.postStockTransferLine(
      ctx,
      {
        type: line.requiresSerialTracking
          ? "unpickSerial"
          : line.requiresBatchTracking
            ? "unpickBatch"
            : "unpickInventory",
        stockTransferId: line.stockTransferId,
        stockTransferLineId: lineId,
        quantity: 0,
        locationId,
        trackedEntityId
      },
      () => "Failed to pick line"
    );
  }
});

/**
 * Pick a scanned serial unit or batch for a stock transfer line.
 *
 * @remarks
 * A serial scan moves one unit; a batch scan moves `quantity` of it, which
 * may not exceed what the line still has to pick. Refused when the line is
 * already fully picked, when the entity is already picked, or when the
 * transfer is Completed.
 *
 * @mcp
 */
export const pickStockTransferLineEntity = defineServiceFn({
  input: z.object({
    lineId: z.string(),
    trackedEntityId: z.string().min(1),
    quantity: z.number().positive(),
    locationId: z.string().min(1)
  }),
  permission: { update: "inventory" },

  async run(ctx, { lineId, trackedEntityId, quantity, locationId }) {
    const line = await service.stockTransferLineOf(ctx, lineId);
    if (line instanceof Error) return line;

    const transferType = line.requiresBatchTracking ? "batch" : "serial";
    // The server function re-checks this under a row lock; refusing a full
    // line here saves the round trip and names the reason.
    const forward = resolveStockTransferPickForward({
      transferType,
      quantity,
      lineQuantity: Number(line.quantity ?? 0),
      pickedQuantity: Number(line.pickedQuantity ?? 0)
    });
    if (!forward.ok) return ctx.error("rule", forward.message);

    return service.postStockTransferLine(
      ctx,
      {
        type: transferType,
        stockTransferId: line.stockTransferId,
        stockTransferLineId: lineId,
        trackedEntityId,
        quantity: forward.quantity,
        locationId
      },
      // Its guard failures (over-pick, already picked) carry the reason.
      (error) => getErrorMessage(error, "Failed to pick line")
    );
  }
});

/**
 * Set one storage unit on stock transfer lines.
 *
 * @remarks
 * `fromStorageUnitId` or `toStorageUnitId`, on every line in `ids`. An empty
 * value clears it. A transfer that is not Draft is locked: reopen it first.
 * Storage rules run when the transfer is released, not here.
 *
 * @mcp
 */
export const updateStockTransferLines = defineServiceFn({
  input: z.object({
    ids: z.array(z.string()).min(1),
    field: z.enum(["fromStorageUnitId", "toStorageUnitId"]),
    value: z.string().nullable()
  }),
  permission: { update: "inventory" },

  async run(ctx, { ids, field, value }) {
    const lines = await ctx.asCaller.supabase
      .from("stockTransferLine")
      .select("id, stockTransfer(status)")
      .in("id", ids)
      .eq("companyId", ctx.company.id);
    if (lines.error) {
      return ctx.error(
        "internal",
        "Failed to load stock transfer lines",
        lines.error
      );
    }
    if (
      lines.data.some((line) =>
        isStockTransferLocked(line.stockTransfer?.status)
      )
    ) {
      return ctx.error("rule", service.STOCK_TRANSFER_LOCKED);
    }

    const update = await ctx.asCaller.supabase
      .from("stockTransferLine")
      .update({
        ...(field === "fromStorageUnitId"
          ? { fromStorageUnitId: value || null }
          : { toStorageUnitId: value || null }),
        updatedBy: ctx.auditUserId,
        updatedAt: datetime.timestamp()
      })
      .in("id", ids)
      .eq("companyId", ctx.company.id);
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update stock transfer lines",
        update.error
      );
    }
    return { ids };
  }
});

// ---------------------------------------------------------------------------
// Warehouse transfers
// ---------------------------------------------------------------------------
/** Every status but these commits the transfer plan. */
const WAREHOUSE_TRANSFER_COMMITS = new Set<string>([
  "To Ship and Receive",
  "To Ship",
  "To Receive",
  "Completed"
]);

/**
 * Set a warehouse transfer's status.
 *
 * @remarks
 * Confirming, shipping, receiving or completing commits the transfer plan:
 * storage rules run on the `warehouseTransfer` surface against each line's
 * destination, and a blocking rule returns its `violations` and `ruleNames`
 * and changes nothing (send `acknowledged: true` to continue past warnings).
 * Draft (reopen) and Cancelled are not commits and run no rules.
 *
 * @mcp
 */
export const setWarehouseTransferStatus = defineServiceFn({
  input: z.object({
    id: z.string(),
    status: z.enum(warehouseTransferStatusType),
    acknowledged: z.boolean().default(false)
  }),
  permission: { update: "inventory" },

  async run(ctx, { id, status, acknowledged }) {
    const transfer = await ctx.asCaller.supabase
      .from("warehouseTransfer")
      .select("id")
      .eq("id", id)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (transfer.error) {
      return ctx.error(
        "internal",
        "Failed to load warehouse transfer",
        transfer.error
      );
    }
    if (!transfer.data) {
      return ctx.error("notFound", service.WAREHOUSE_TRANSFER_NOT_FOUND);
    }

    if (WAREHOUSE_TRANSFER_COMMITS.has(status)) {
      const lines = await ctx.asSystem.supabase
        .from("warehouseTransferLine")
        .select("id, itemId, toStorageUnitId, toLocationId, quantity")
        .eq("transferId", id)
        .eq("companyId", ctx.company.id);
      const rules = await service.storageRuleViolations(
        ctx,
        ["warehouseTransfer"],
        (lines.data ?? []).map((line) => ({
          lineId: line.id,
          itemId: line.itemId,
          storageUnitId: line.toStorageUnitId,
          quantity: Number(line.quantity ?? 0),
          locationId: line.toLocationId
        }))
      );
      if (
        rules.violations.length > 0 &&
        isBlocked(rules.violations, acknowledged)
      ) {
        return rules satisfies Blocked;
      }
    }

    const update = await service.updateWarehouseTransferStatus(
      ctx.asCaller.supabase,
      id,
      status,
      ctx.auditUserId
    );
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update warehouse transfer status",
        update.error
      );
    }
    return { id, status };
  }
});
const warehouseTransferLineFields = {
  quantity: z.number().min(0.0001, "Quantity must be greater than 0"),
  fromStorageUnitId: z.string().optional(),
  toStorageUnitId: z.string().optional(),
  notes: z.string().optional()
};

/**
 * Add a line to a Draft warehouse transfer.
 *
 * @remarks
 * The line moves `quantity` of the item between the transfer's locations.
 * A transfer that is not Draft is locked: reopen it first.
 *
 * @mcp
 */
export const createWarehouseTransferLine = defineServiceFn({
  input: z.object({
    transferId: z.string(),
    itemId: z.string().min(1),
    unitOfMeasureCode: z.string().optional(),
    ...warehouseTransferLineFields
  }),
  permission: { update: "inventory" },

  async run(ctx, { transferId, ...line }) {
    const transfer = await service.unlockedWarehouseTransfer(ctx, transferId);
    if (transfer instanceof Error) return transfer;

    const created = await service.upsertWarehouseTransferLine(
      ctx.asCaller.supabase,
      {
        ...line,
        transferId,
        fromLocationId: transfer.fromLocationId,
        toLocationId: transfer.toLocationId,
        companyId: ctx.company.id,
        createdBy: ctx.auditUserId
      }
    );
    if (created.error) {
      return ctx.error(
        "internal",
        "Failed to create warehouse transfer line",
        created.error
      );
    }
    return { id: created.data.id };
  }
});
/**
 * Update a line of a Draft warehouse transfer.
 *
 * @remarks
 * Sets the line's quantity, storage units and notes. A transfer that is not
 * Draft is locked: reopen it first.
 *
 * @mcp
 */
export const updateWarehouseTransferLine = defineServiceFn({
  input: z.object({
    transferId: z.string(),
    id: z.string(),
    ...warehouseTransferLineFields
  }),
  permission: { update: "inventory" },

  async run(ctx, { transferId, id, ...line }) {
    const transfer = await service.unlockedWarehouseTransfer(ctx, transferId);
    if (transfer instanceof Error) return transfer;
    const existing = await service.warehouseTransferLineOf(ctx, {
      transferId,
      id
    });
    if (existing instanceof Error) return existing;

    const updated = await service.upsertWarehouseTransferLine(
      ctx.asCaller.supabase,
      {
        id,
        ...line,
        updatedBy: ctx.auditUserId
      }
    );
    if (updated.error) {
      return ctx.error(
        "internal",
        "Failed to update warehouse transfer line",
        updated.error
      );
    }
    return { id };
  }
});

/**
 * Delete a line of a Draft warehouse transfer.
 *
 * @remarks
 * A transfer that is not Draft is locked: reopen it first.
 *
 * @mcp destructive
 */
export const removeWarehouseTransferLine = defineServiceFn({
  input: z.object({ transferId: z.string(), id: z.string() }),
  permission: { update: "inventory" },

  async run(ctx, { transferId, id }) {
    const transfer = await service.unlockedWarehouseTransfer(ctx, transferId);
    if (transfer instanceof Error) return transfer;
    const existing = await service.warehouseTransferLineOf(ctx, {
      transferId,
      id
    });
    if (existing instanceof Error) return existing;

    const deleted = await service.deleteWarehouseTransferLine(
      ctx.asCaller.supabase,
      id
    );
    if (deleted.error) {
      return ctx.error(
        "internal",
        "Failed to delete warehouse transfer line",
        deleted.error
      );
    }
    return { id };
  }
});

// ---------------------------------------------------------------------------
// Inventory counts and adjustments
// ---------------------------------------------------------------------------

/**
 * Create an inventory count.
 *
 * @remarks
 * Creates a Draft count at a location and snapshots its on-hand into count
 * lines: one per item, storage unit and tracked entity with stock history,
 * Rejected and Consumed lots left out. `storageUnitIds` and `itemType`
 * narrow what is counted. If the snapshot fails the count is deleted, so no
 * empty count is left behind.
 *
 * @mcp
 */
export const createInventoryCount = defineServiceFn({
  input: z.object({
    locationId: z.string().min(1),
    isBlind: z.boolean().default(false),
    notes: z.string().optional(),
    storageUnitIds: z.array(z.string()).optional(),
    itemType: z.enum(inventoryItemTypes).optional()
  }),
  permission: { create: "inventory" },

  async run(ctx, { locationId, isBlind, notes, storageUnitIds, itemType }) {
    const companyId = ctx.company.id;
    const sequence = await getNextSequence(
      ctx.asCaller.supabase,
      "inventoryCount",
      companyId
    );
    if (sequence.error || !sequence.data) {
      return ctx.error(
        "internal",
        "Failed to generate inventory count id",
        sequence.error
      );
    }

    // The scope it was generated with, recorded for a future "regenerate from
    // current stock while Draft". Not read back yet.
    const scope = {
      ...(storageUnitIds && storageUnitIds.length > 0
        ? { storageUnitIds }
        : {}),
      ...(itemType ? { itemFilter: { type: itemType } } : {})
    };

    const created = await service.insertInventoryCount(ctx.asCaller.supabase, {
      inventoryCountId: sequence.data as string,
      locationId,
      isBlind,
      notes: notes ?? null,
      scope,
      companyId,
      createdBy: ctx.auditUserId
    });
    if (created.error || !created.data) {
      return ctx.error(
        "internal",
        "Failed to create inventory count",
        created.error
      );
    }

    // The header and the snapshot are not one transaction: a failed snapshot
    // deletes the header instead of leaving an empty Draft count.
    try {
      await service.generateInventoryCountLines(ctx.asSystem.pg, {
        inventoryCountId: created.data.id,
        companyId,
        locationId,
        createdBy: ctx.auditUserId,
        storageUnitIds,
        itemType
      });
    } catch (error) {
      await service.deleteInventoryCount(
        ctx.asCaller.supabase,
        created.data.id,
        companyId
      );
      return ctx.error("internal", "Failed to generate count lines", error);
    }
    return { id: created.data.id };
  }
});

/**
 * Post a confirmed inventory count.
 *
 * @remarks
 * Only a Pending (confirmed) count posts. Each counted line's variance
 * against its snapshot is booked as an inventory adjustment, all in one
 * transaction: ledger entries, cost layers and the journal. Posted is
 * final. A count with lines that cannot post (a serial line counted as
 * anything but 0 or 1) is not posted and returns `invalidLineIds` with the
 * reason in `message`.
 *
 * @mcp
 */
export const postInventoryCount = defineServiceFn({
  input: z.object({ inventoryCountId: z.string() }),
  permission: { update: "inventory" },

  async run(ctx, { inventoryCountId }) {
    const header = await service.getInventoryCount(
      ctx.asCaller.supabase,
      inventoryCountId,
      ctx.company.id
    );
    if (header.data?.status !== "Pending") {
      return ctx.error(
        "rule",
        "Only a confirmed (pending) count can be made effective"
      );
    }

    const posted = await invokePosting(
      ctx,
      "post-inventory-count",
      { inventoryCountId },
      service.postInventoryCount
    );
    if (posted.error) {
      return service.inventoryCountPostingFailure(ctx, posted.error);
    }
    return { inventoryCountId };
  }
});

/**
 * Adjust an item's stock.
 *
 * @remarks
 * A positive or negative adjustment, a set quantity, a scrap (with its scrap
 * reason) or an unscrap of a Scrapped tracked entity. It writes the ledger
 * entry, updates the tracked entity, maintains cost layers and posts the
 * journal in one transaction. Storage rules run first on the
 * `inventoryAdjustment` surface and, when a storage unit is named, on `pick`
 * (a decrease or scrap) or `place` (an increase or unscrap): a blocking rule
 * returns its `violations` and `ruleNames` and changes nothing; send
 * `acknowledged: true` to adjust past warnings.
 *
 * Every adjustment but an unscrap needs `locationId`; an unscrap resolves its
 * location, bin and cost from the original scrap.
 *
 * @mcp
 */
export const adjustInventory = defineServiceFn({
  input: z
    .object({
      itemId: z.string().min(1),
      adjustmentType: z.enum(inventoryAdjustmentTypes),
      /** A positive magnitude; the type says which way it moves. */
      quantity: z.number().min(0),
      locationId: z.string().optional(),
      storageUnitId: z.string().optional(),
      originalStorageUnitId: z.string().optional(),
      trackedEntityId: z.string().optional(),
      readableId: z.string().optional(),
      expirationDate: z.string().optional(),
      comment: z.string().optional(),
      scrapReasonId: z.string().optional(),
      unscrapOfItemLedgerId: z.string().optional(),
      acknowledged: z.boolean().default(false)
    })
    .refine((d) => d.adjustmentType !== "Scrap" || !!d.scrapReasonId, {
      path: ["scrapReasonId"],
      message: "Scrap reason is required"
    })
    .refine((d) => d.adjustmentType === "Unscrap" || !!d.locationId, {
      path: ["locationId"],
      message: "Location is required"
    }),
  // The adjustment route's gate, and the update the posting itself requires.
  permission: { create: "inventory", update: "inventory" },

  async run(ctx, { acknowledged, ...adjustment }) {
    const serial = await service.serialQuantityRefusal(
      ctx,
      adjustment.itemId,
      adjustment.quantity
    );
    if (serial) return serial;

    const line = [
      {
        lineId: adjustment.itemId,
        itemId: adjustment.itemId,
        storageUnitId: adjustment.storageUnitId ?? null,
        quantity: Number(adjustment.quantity ?? 0),
        locationId: adjustment.locationId ?? null
      }
    ];
    const rules = await service.storageRuleViolations(
      ctx,
      service.adjustmentRuleSurfaces(
        adjustment.adjustmentType,
        adjustment.storageUnitId
      ),
      line
    );
    const violations = dedupeViolations(rules.violations);
    if (violations.length > 0 && isBlocked(violations, acknowledged)) {
      return { violations, ruleNames: rules.ruleNames } satisfies Blocked;
    }

    const posted = await invokePosting(
      ctx,
      "post-inventory-adjustment",
      adjustment,
      service.postInventoryAdjustment
    );
    if (posted.error) {
      return service.postingFailure(
        ctx,
        posted.error,
        "Failed to create manual inventory adjustment"
      );
    }
    return { itemLedgerId: posted.data.itemLedger?.id ?? null };
  }
});

// ---------------------------------------------------------------------------
// Storage units
// ---------------------------------------------------------------------------

/**
 * Delete a storage unit.
 *
 * @remarks
 * A unit with nested units is refused unless `cascade` is set, which deletes
 * the whole subtree.
 *
 * @mcp destructive
 */
export const removeStorageUnit = defineServiceFn({
  input: z.object({
    storageUnitId: z.string(),
    cascade: z.boolean().default(false)
  }),
  permission: { delete: "inventory" },

  async run(ctx, { storageUnitId, cascade }) {
    const unit = await ctx.asCaller.supabase
      .from("storageUnit")
      .select("id")
      .eq("id", storageUnitId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (unit.error) {
      return ctx.error("internal", "Failed to delete storage unit", unit.error);
    }
    if (!unit.data) {
      return ctx.error("notFound", "The storage unit could not be found");
    }

    const deleted = cascade
      ? await service.deleteStorageUnitCascade(
          ctx.asCaller.supabase,
          storageUnitId
        )
      : await service.deleteStorageUnit(ctx.asCaller.supabase, storageUnitId);
    if (deleted.error) {
      return ctx.error(
        "internal",
        "Failed to delete storage unit",
        deleted.error
      );
    }
    return { storageUnitId, cascade };
  }
});

// ---------------------------------------------------------------------------
// Picking lists
// ---------------------------------------------------------------------------

/**
 * Set a picking list's status.
 *
 * @remarks
 * Reopening a Completed, Partial or Cancelled list needs the inventory delete
 * permission. Finishing (Completed) checks the lines first: with lines left
 * unpicked, the company's incomplete picking list policy refuses (`error`) or
 * returns `needsAcknowledgement` with those lines until the call is repeated
 * with `acknowledged` (`warn`). A list with unpicked or short lines finishes
 * Partial, not Completed.
 *
 * @mcp
 */
export const setPickingListStatus = defineServiceFn({
  input: z.object({
    pickingListId: z.string(),
    status: z.enum(pickingListStatusType),
    acknowledged: z.boolean().optional()
  }),
  permission: { update: "inventory" },

  async run(ctx, { pickingListId, status, acknowledged }) {
    const client = ctx.asCaller.supabase;
    const companyId = ctx.company.id;

    const current = await client
      .from("pickingList")
      .select("status")
      .eq("id", pickingListId)
      .eq("companyId", companyId)
      .maybeSingle();
    if (current.error) {
      return ctx.error(
        "internal",
        "Failed to read the picking list",
        current.error
      );
    }
    if (!current.data) return ctx.error("notFound", "Picking list not found");

    if (
      isPickingListLocked(current.data.status) &&
      !isPickingListLocked(status) &&
      !ctx.can({ delete: "inventory" })
    ) {
      return ctx.error(
        "forbidden",
        "Reopening a closed picking list needs the inventory delete permission"
      );
    }

    let finalStatus = status;
    if (status === "Completed") {
      const [lines, settings] = await Promise.all([
        service.getUnresolvedPickingListLines(client, pickingListId, companyId),
        getCompanySettings(client, companyId)
      ]);
      if (lines.error) {
        return ctx.error(
          "internal",
          "Failed to check picking list lines",
          lines.error
        );
      }
      // Fail closed: an unreadable policy must not fall back to the
      // bypassable 'warn' default.
      if (settings.error || !settings.data) {
        return ctx.error(
          "internal",
          "Failed to read the picking list completion policy",
          settings.error
        );
      }
      const finish = finishPickingList({
        unresolvedItemNames: lines.unresolved.map((line) => line.itemName),
        hasShort: lines.hasShort,
        policy: settings.data.incompletePickingListPolicy,
        acknowledged: acknowledged ?? false
      });
      if (finish.outcome === "refuse") return ctx.error("rule", finish.message);
      if (finish.outcome === "ask") {
        return {
          needsAcknowledgement: true as const,
          unresolvedLines: lines.unresolved
        };
      }
      finalStatus = finish.status;
    }

    const update = await service.updatePickingListStatus(
      client,
      pickingListId,
      finalStatus,
      ctx.auditUserId
    );
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update picking list status",
        update.error
      );
    }

    if (finalStatus === "Completed" || finalStatus === "Partial") {
      // Partial means a line could not be filled: the material-availability
      // half of job cycle time. The status is the discriminator, so a list
      // that goes Partial and later Completed records both.
      trackWorkEvent(
        "picking_list_completed",
        {
          companyId,
          userId: ctx.auditUserId,
          pickingListId,
          finalStatus,
          source: "erp"
        },
        { discriminator: finalStatus }
      );
    }
    return { pickingListId, status: finalStatus };
  }
});

/**
 * Update a Draft picking list's details.
 *
 * @remarks
 * Location, assignee, due date, notes and custom fields. A list past Draft is
 * locked: reopen it first.
 *
 * @mcp
 */
export const updatePickingList = defineServiceFn({
  input: z.object({
    pickingListId: z.string(),
    locationId: z.string().min(1),
    assignee: z.string().optional(),
    dueDate: z.string().optional(),
    notes: optionalTiptapDoc,
    customFields: z.record(z.string(), z.unknown()).optional()
  }),
  permission: { update: "inventory" },

  async run(ctx, { pickingListId, customFields, ...fields }) {
    const existing = await service.getPickingList(
      ctx.asCaller.supabase,
      pickingListId
    );
    if (existing.error || !existing.data) {
      return ctx.error("notFound", "Picking list not found", existing.error);
    }
    if (existing.data.status !== "Draft") {
      return ctx.error(
        "rule",
        "Cannot modify a locked picking list. Reopen it first."
      );
    }

    const updated = await service.upsertPickingList(ctx.asCaller.supabase, {
      id: pickingListId,
      pickingListId: existing.data.pickingListId,
      ...fields,
      updatedBy: ctx.auditUserId,
      customFields: customFields as Json | undefined
    });
    if (updated.error) {
      return ctx.error(
        "internal",
        "Failed to update picking list",
        updated.error
      );
    }
    return { pickingListId };
  }
});

const pickingListLineInput = {
  pickingListId: z.string(),
  pickingListLineId: z.string()
};

/**
 * Pick a picking list line, or mark it short.
 *
 * @remarks
 * Sets the line's picked quantity (0 unpicks); with `markShort` the line is
 * Short at that quantity. The line must be on the list.
 *
 * @mcp
 */
export const pickPickingListLineChecked = defineServiceFn({
  input: z.object({
    ...pickingListLineInput,
    quantity: z.number().min(0),
    markShort: z.boolean().optional()
  }),
  permission: { update: "inventory" },

  async run(ctx, { pickingListId, pickingListLineId, quantity, markShort }) {
    const owned = await refuseUnlessOwned(ctx, "pickingListLine", {
      id: pickingListLineId,
      pickingListId
    });
    if (owned) return owned;

    const result = await service.pickPickingListLine(
      ctx.asSystem.supabase,
      ctx.asSystem.pg,
      {
        pickingListLineId,
        quantity,
        markShort,
        userId: ctx.auditUserId,
        companyId: ctx.company.id
      }
    );
    if (result.error) return service.pickRefusal(ctx, result.error);
    return result.data;
  }
});

/**
 * Pick a serial or batch for a picking list line, or put it back.
 *
 * @remarks
 * Picks `quantity` of the tracked entity (from `fromStorageUnitId` when
 * given) onto the line; with `unpick` the entity's pick is undone. The line
 * must be on the list.
 *
 * @mcp
 */
export const pickPickingListLineEntity = defineServiceFn({
  input: z.object({
    ...pickingListLineInput,
    trackedEntityId: z.string(),
    fromStorageUnitId: z.string().nullable().optional(),
    quantity: z.number().min(0),
    unpick: z.boolean().optional()
  }),
  permission: { update: "inventory" },

  async run(
    ctx,
    {
      pickingListId,
      pickingListLineId,
      trackedEntityId,
      fromStorageUnitId,
      quantity,
      unpick
    }
  ) {
    const owned = await refuseUnlessOwned(ctx, "pickingListLine", {
      id: pickingListLineId,
      pickingListId
    });
    if (owned) return owned;

    const result = await service.setPickingListLineTrackedEntity(
      ctx.asSystem.supabase,
      ctx.asSystem.pg,
      {
        pickingListLineId,
        trackedEntityId,
        fromStorageUnitId: fromStorageUnitId ?? null,
        quantity,
        unpick: unpick ?? false,
        userId: ctx.auditUserId,
        companyId: ctx.company.id
      }
    );
    if (result.error) return service.pickRefusal(ctx, result.error);
    return result.data;
  }
});
// ---------------------------------------------------------------------------
// Kanbans
// ---------------------------------------------------------------------------

/** What a kanban scan did, for the caller to open. */
export type KanbanScan =
  /** A Make kanban that already has a job: the collision page. */
  | { type: "collision" }
  /**
   * The job it made. `operationId` is its first operation when the kanban
   * releases the job; `startAs` how to start it when the kanban starts it.
   * `message` says why the job was not released, or that its method could
   * not be copied.
   */
  | {
      type: "job";
      jobId: string;
      operationId: string | null;
      startAs: "Setup" | "Labor" | "Machine" | null;
      message: string | null;
    }
  | { type: "purchaseOrder"; purchaseOrderId: string }
  | { type: "stockTransfer"; stockTransferId: string };

/**
 * Replenish a kanban: what scanning its card does.
 *
 * @remarks
 * Make: creates a Hard Deadline job for the kanban's item and quantity, due
 * after the item's lead time, copies the item's method and links the job to
 * the kanban; with auto-release it runs the release checks, then releases the
 * job (`releaseCheckedJobs`) and runs the location's schedule. A job that
 * fails the checks, or whose method could not be copied, stays Draft and
 * `message` names the problems. A kanban that already has a job is a
 * collision. Buy: adds a line to the supplier's open Draft or Planned purchase
 * order, or a new Draft one, priced from the supplier part in the order's
 * currency. Transfer: releases a stock transfer to the kanban's storage unit
 * (`kanban-replenish`, as the scanner).
 */
export const scanKanban = defineServiceFn({
  input: z.object({ kanbanId: z.string() }),
  // Safe only unpublished (an employee-only route; Make creates jobs as the
  // system): give it a real rule before it is ever tagged @mcp.
  permission: {},

  async run(ctx, { kanbanId }): Promise<KanbanScan | CarbonError> {
    const client = ctx.asCaller.supabase;
    const serviceRole = ctx.asSystem.supabase;
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;

    const kanban = await service.getKanban(client, kanbanId, companyId);
    if (kanban.error || !kanban.data) {
      return ctx.error("notFound", "Kanban is not active", kanban.error);
    }
    const card = kanban.data;

    /** No one at a kanban card can choose a purchase order, so unlike
     *  `releaseJobs` a supplier's newest Draft PO is reused rather than a
     *  blocker. */
    async function releaseKanbanJob(
      jobId: string,
      locationId: string
    ): Promise<{ released: boolean; message: string | null }> {
      const job = await serviceRole
        .from("job")
        .select("jobId")
        .eq("id", jobId)
        .eq("companyId", companyId)
        .single();
      const readiness = await getJobReleaseReadiness(
        serviceRole,
        [jobId],
        companyId
      );
      const ready = readiness.data?.jobs[0];
      if (job.error || readiness.error || !ready) {
        logger.error("Failed to check a kanban job for release", {
          companyId,
          jobId,
          error: job.error ?? readiness.error
        });
        return {
          released: false,
          message: `${job.data?.jobId ?? "The job"} was created but could not be checked for release. Release it from the job.`
        };
      }

      const problems = jobReleaseProblems(ready);
      if (problems.length > 0) {
        return {
          released: false,
          message: `${job.data.jobId} was created but not released: ${problems.join("; ")}`
        };
      }

      // As the system, like the job it releases: the scanner may not hold
      // production update, and the status write runs on the caller's client.
      const system = createServiceContext({
        actor: { type: "system", onBehalfOf: userId },
        company: ctx.company,
        caller: serviceRole,
        system: () => serviceRole,
        pg: () => ctx.asSystem.pg,
        kv: () => ctx.kv
      });
      const result = await releaseCheckedJobs(system, {
        jobIds: [jobId],
        purchaseOrdersBySupplierId: Object.fromEntries(
          (readiness.data?.suppliers ?? []).map((supplier) => [
            supplier.supplierId,
            [...supplier.draftPurchaseOrders].sort((a, b) =>
              b.purchaseOrderId.localeCompare(a.purchaseOrderId)
            )[0]?.id ?? "new"
          ])
        ),
        source: "kanban"
      });
      const failure = result.error ?? result.data.failure;
      const released = result.data?.releasedJobIds.includes(jobId) ?? false;
      if (failure) {
        logger.error("Failed to release a kanban job", {
          companyId,
          jobId,
          error: failure
        });
      }
      for (const warning of result.data?.warnings ?? []) {
        logger.warn("A kanban job was released with a warning", {
          companyId,
          jobId,
          warning: warning.message
        });
      }

      // After the status is persisted: the scheduler only places released jobs.
      if (released) {
        try {
          await runLocationSchedule({
            db: ctx.asSystem.pg,
            client: serviceRole,
            locationId,
            companyId,
            userId
          });
        } catch (error) {
          logger.error("Failed to schedule a kanban job", {
            companyId,
            jobId,
            error
          });
        }
      }

      return {
        released,
        message: failure ? `${job.data.jobId}: ${failure.message}` : null
      };
    }

    if (card.replenishmentSystem === "Make") {
      if (card.jobReadableId) return { type: "collision" };
      if (!card.itemId) return ctx.error("rule", "Failed to create job");

      const [manufacturing, defaultStorageUnit] = await Promise.all([
        getItemReplenishment(client, card.itemId, companyId),
        getDefaultStorageUnitForJob(
          client,
          card.itemId,
          card.locationId!,
          companyId
        )
      ]);

      // No location on the kanban → the company calendar.
      const startDate = datetime.today(
        card.locationId
          ? await getLocationTimeZone(client, card.locationId, companyId)
          : await getCompanyTimeZone(client, companyId)
      );
      const dueDate = startDate
        .add({ days: manufacturing.data?.leadTime ?? 7 })
        .toString();

      const createdJob = await insertJob(
        serviceRole,
        ctx.asSystem.pg,
        {
          itemId: card.itemId,
          quantity: card.quantity!,
          locationId: card.locationId!,
          storageUnitId: card.storageUnitId || defaultStorageUnit || undefined,
          unitOfMeasureCode: card.purchaseUnitOfMeasureCode!,
          deadlineType: "Hard Deadline",
          startDate: startDate.toString(),
          dueDate,
          companyId,
          createdBy: userId
        },
        { skipMethod: true, skipRecalculate: true, source: "kanban" }
      );
      if (createdJob.error || !createdJob.data) {
        return ctx.error("internal", "Failed to create job", createdJob.error);
      }
      const jobId = createdJob.data.id;

      const [method, associated] = await Promise.all([
        upsertJobMethod(serviceRole, ctx.asSystem.pg, "itemToJob", {
          sourceId: card.itemId,
          targetId: jobId,
          companyId,
          userId,
          configuration: undefined
        }),
        updateKanbanJob(serviceRole, {
          id: card.id!,
          jobId,
          companyId,
          userId
        })
      ]);
      if (associated.error) {
        return ctx.error(
          "internal",
          "Failed to associate kanban with job",
          associated.error
        );
      }

      if (method.error) {
        logger.error("Kanban operation failed", { error: method.error });
      }
      const release = method.error
        ? {
            released: false,
            message: `${createdJob.data.jobId} was created, but its method could not be copied. Use Get Method on the job before releasing it.`
          }
        : card.autoRelease
          ? await releaseKanbanJob(jobId, card.locationId!)
          : { released: false, message: null };

      const operation = release.released
        ? await getActiveJobOperationByJobId(client, jobId, companyId)
        : null;
      if (!operation) {
        return {
          type: "job",
          jobId,
          operationId: null,
          startAs: null,
          message: release.message
        };
      }
      const startAs = !card.autoStartJob
        ? null
        : operation.setupTime
          ? "Setup"
          : operation.machineTime && !operation.laborTime
            ? "Machine"
            : "Labor";
      return {
        type: "job",
        jobId,
        operationId: operation.id,
        startAs,
        message: release.message
      };
    }

    if (card.replenishmentSystem === "Buy") {
      const existing = await client
        .from("purchaseOrder")
        .select("id, currencyCode, exchangeRate")
        .eq("supplierId", card.supplierId!)
        .in("status", ["Planned", "Draft"])
        .eq("companyId", companyId)
        .maybeSingle();

      let purchaseOrderId = existing.data?.id;
      let orderCurrencyCode = existing.data?.currencyCode ?? null;
      let orderExchangeRate = existing.data?.exchangeRate ?? 1;

      if (!purchaseOrderId) {
        const created = await insertPurchaseOrder(client, {
          supplierId: card.supplierId!,
          status: "Draft",
          purchaseOrderType: "Purchase",
          companyId,
          companyGroupId: ctx.company.groupId,
          createdBy: userId
        });
        if (created.error || !created.data) {
          return ctx.error(
            "internal",
            "Failed to create purchase order",
            created.error
          );
        }
        purchaseOrderId = created.data.id;
        orderCurrencyCode = null;
        orderExchangeRate = created.data.exchangeRate;
      }

      const [item, supplierPart, pickMethod, company] = await Promise.all([
        client
          .from("item")
          .select(
            "name, readableIdWithRevision, type, unitOfMeasureCode, itemCost(unitCost), itemReplenishment(purchasingUnitOfMeasureCode, conversionFactor, leadTime)"
          )
          .eq("id", card.itemId!)
          .eq("companyId", companyId)
          .single(),
        client
          .from("supplierPart")
          .select("*")
          .eq("itemId", card.itemId!)
          .eq("companyId", companyId)
          .eq("supplierId", card.supplierId!)
          .maybeSingle(),
        client
          .from("pickMethod")
          .select("defaultStorageUnitId")
          .eq("itemId", card.itemId!)
          .eq("companyId", companyId)
          .eq("locationId", card.locationId!)
          .maybeSingle(),
        client
          .from("company")
          .select("baseCurrencyCode")
          .eq("id", companyId)
          .single()
      ]);

      // The line is in the ORDER's currency: the supplier part's price
      // converts from its own currency at today's rate, the item cost from
      // base.
      const baseCurrencyCode = company.data?.baseCurrencyCode ?? "USD";
      const order = {
        currencyCode: orderCurrencyCode ?? baseCurrencyCode,
        exchangeRate: orderExchangeRate
      };
      const pricing = supplierPart.data
        ? await getSupplierPartPricing(
            client,
            supplierPart.data,
            baseCurrencyCode,
            order.currencyCode
          )
        : null;
      if (pricing?.error) {
        return ctx.error("internal", pricing.error.message, pricing.error);
      }
      if (item.error) {
        return ctx.error("internal", "Failed to get item", item.error);
      }
      const supplierUnitPrice = resolveSupplierPrice(
        pricing?.data ?? null,
        card.quantity!,
        order,
        convertUnitPrice(
          item.data.itemCost?.[0]?.unitCost ?? 0,
          { currencyCode: baseCurrencyCode, exchangeRate: 1 },
          order
        )
      );

      const line = await upsertPurchaseOrderLine(client, {
        purchaseOrderId,
        purchaseOrderLineType: item.data.type as never,
        itemId: card.itemId!,
        purchaseQuantity: card.quantity!,
        supplierUnitPrice,
        supplierShippingCost: 0,
        supplierTaxAmount: 0,
        taxPercent: 0,
        exchangeRate: order.exchangeRate,
        purchaseUnitOfMeasureCode: card.purchaseUnitOfMeasureCode!,
        inventoryUnitOfMeasureCode:
          item.data.unitOfMeasureCode || card.purchaseUnitOfMeasureCode!,
        conversionFactor:
          card.conversionFactor ||
          item.data.itemReplenishment?.conversionFactor ||
          1,
        locationId: card.locationId!,
        storageUnitId:
          card.storageUnitId ||
          pickMethod.data?.defaultStorageUnitId ||
          undefined,
        companyId,
        createdBy: userId
      });
      if (line.error) {
        return ctx.error(
          "internal",
          "Failed to create purchase order line",
          line.error
        );
      }
      return { type: "purchaseOrder", purchaseOrderId };
    }

    if (card.replenishmentSystem === "Transfer") {
      if (!card.itemId) {
        return ctx.error("rule", "Failed to create stock transfer");
      }
      // kanban-replenish re-reads the kanban under companyId, checks both
      // storage units belong to the kanban's location, and writes the
      // Released transfer with its kanbanId. It runs as the scanner: a scan
      // needs the inventory create permission the stock transfer's RLS
      // rule checks.
      const replenish = await invokePosting(
        { client, db: ctx.asSystem.pg, companyId, userId },
        "kanban-replenish",
        { mode: "scan", kanbanId },
        service.replenishKanban,
        { as: service.replenishKanbanPermission }
      );
      if (replenish.error) {
        return ctx.error(
          "internal",
          "Failed to create stock transfer",
          replenish.error
        );
      }
      const outcome = replenish.data.results[0];
      if (outcome?.outcome === "invalid") {
        return ctx.error("rule", outcome.reason);
      }
      if (outcome?.outcome === "created") {
        return { type: "stockTransfer", stockTransferId: outcome.id };
      }
      return ctx.error("internal", "Failed to create stock transfer");
    }

    return ctx.error("rule", `${card.replenishmentSystem} is not supported`);
  }
});
/**
 * Delete batch property
 *
 * @mcp destructive
 */
export const deleteBatchProperty = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const owned = await refuseUnlessOwned(ctx, "batchProperty", {
      id: input.id
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.deleteBatchProperty(
        ctx.asCaller.supabase,
        input.id as never
      )
    );
  }
});

/**
 * Delete kanban
 *
 * @mcp destructive
 */
export const deleteKanban = defineServiceFn({
  input: z.looseObject({ kanbanId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const owned = await refuseUnlessOwned(ctx, "kanban", {
      id: input.kanbanId
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.deleteKanban(ctx.asCaller.supabase, input.kanbanId as never)
    );
  }
});

/**
 * Delete receipt
 *
 * @remarks
 * A posted receipt cannot be deleted; void it instead.
 *
 * @mcp destructive
 */
export const deleteReceipt = defineServiceFn({
  input: z.looseObject({ receiptId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const receipt = await ctx.asCaller.supabase
      .from("receipt")
      .select("postingDate")
      .eq("id", input.receiptId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (receipt.error) {
      return ctx.error("internal", "Failed to get receipt", receipt.error);
    }
    if (!receipt.data) return ctx.error("notFound", "Receipt not found");
    if (receipt.data.postingDate) {
      return ctx.error("rule", "Cannot delete a posted receipt");
    }
    return unwrap(
      ctx,
      await service.deleteReceipt(
        ctx.asCaller.supabase,
        input.receiptId as never
      )
    );
  }
});

/**
 * Delete receipt line
 *
 * @remarks
 * Only a Draft receipt's lines can be deleted.
 *
 * @mcp destructive
 */
export const deleteReceiptLine = defineServiceFn({
  input: z.looseObject({ receiptLineId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const line = await ctx.asCaller.supabase
      .from("receiptLine")
      .select("id, receipt!receiptLine_receiptId_fkey(status)")
      .eq("id", input.receiptLineId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (line.error) {
      return ctx.error("internal", "Failed to load receipt line", line.error);
    }
    if (!line.data?.receipt) {
      return ctx.error("notFound", "The receipt line could not be found");
    }
    if (line.data.receipt.status !== "Draft") {
      return ctx.error("rule", RECEIPT_LOCKED);
    }
    return unwrap(
      ctx,
      await service.deleteReceiptLine(
        ctx.asCaller.supabase,
        input.receiptLineId as never
      )
    );
  }
});

/**
 * Delete shipment
 *
 * @remarks
 * A posted shipment cannot be deleted; void it instead.
 *
 * @mcp destructive
 */
export const deleteShipment = defineServiceFn({
  input: z.looseObject({ shipmentId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const shipment = await ctx.asCaller.supabase
      .from("shipment")
      .select("postingDate")
      .eq("id", input.shipmentId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (shipment.error) {
      return ctx.error("internal", "Failed to get shipment", shipment.error);
    }
    if (!shipment.data) return ctx.error("notFound", "Shipment not found");
    if (shipment.data.postingDate) {
      return ctx.error("rule", "Cannot delete a posted shipment");
    }
    return unwrap(
      ctx,
      await service.deleteShipment(
        ctx.asCaller.supabase,
        input.shipmentId as never
      )
    );
  }
});

/**
 * Delete shipment line
 *
 * @remarks
 * Only a Draft shipment's lines can be deleted.
 *
 * @mcp destructive
 */
export const deleteShipmentLine = defineServiceFn({
  input: z.looseObject({ shipmentLineId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const line = await ctx.asCaller.supabase
      .from("shipmentLine")
      .select("id, shipment!shipmentLine_shipmentId_fkey(status)")
      .eq("id", input.shipmentLineId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (line.error) {
      return ctx.error("internal", "Failed to load shipment line", line.error);
    }
    if (!line.data?.shipment) {
      return ctx.error("notFound", "The shipment line could not be found");
    }
    if (line.data.shipment.status !== "Draft") {
      return ctx.error("rule", SHIPMENT_LOCKED);
    }
    return unwrap(
      ctx,
      await service.deleteShipmentLine(
        ctx.asCaller.supabase,
        input.shipmentLineId as never
      )
    );
  }
});

/**
 * Delete shipping method
 *
 * @mcp destructive
 */
export const deleteShippingMethod = defineServiceFn({
  input: z.looseObject({ shippingMethodId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const owned = await refuseUnlessOwned(ctx, "shippingMethod", {
      id: input.shippingMethodId
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.deleteShippingMethod(
        ctx.asCaller.supabase,
        input.shippingMethodId as never
      )
    );
  }
});

/**
 * Delete stock transfer
 *
 * @remarks
 * Only a Draft transfer can be deleted: reopen a locked one first.
 *
 * @mcp destructive
 */
export const deleteStockTransfer = defineServiceFn({
  input: z.looseObject({ stockTransferId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const transfer = await service.unlockedStockTransfer(
      ctx,
      input.stockTransferId
    );
    if (transfer instanceof Error) return transfer;
    return unwrap(
      ctx,
      await service.deleteStockTransfer(
        ctx.asCaller.supabase,
        input.stockTransferId as never
      )
    );
  }
});

/**
 * Delete stock transfer line
 *
 * @remarks
 * Only a line of a Draft transfer can be deleted: reopen a locked one first.
 *
 * @mcp destructive
 */
export const deleteStockTransferLine = defineServiceFn({
  input: z.looseObject({ stockTransferLineId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const line = await ctx.asCaller.supabase
      .from("stockTransferLine")
      .select("stockTransferId")
      .eq("id", input.stockTransferLineId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (line.error) {
      return ctx.error(
        "internal",
        "Failed to load stock transfer line",
        line.error
      );
    }
    if (!line.data) {
      return ctx.error("notFound", "Stock transfer line not found");
    }
    const transfer = await service.unlockedStockTransfer(
      ctx,
      line.data.stockTransferId
    );
    if (transfer instanceof Error) return transfer;
    return unwrap(
      ctx,
      await service.deleteStockTransferLine(
        ctx.asCaller.supabase,
        input.stockTransferLineId as never
      )
    );
  }
});

/**
 * Delete warehouse transfer
 *
 * @mcp destructive
 */
export const deleteWarehouseTransfer = defineServiceFn({
  input: z.looseObject({ transferId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const owned = await refuseUnlessOwned(ctx, "warehouseTransfer", {
      id: input.transferId
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.deleteWarehouseTransfer(
        ctx.asCaller.supabase,
        input.transferId as never
      )
    );
  }
});

/**
 * Keyset-paginated item-ledger activity for the per-item Activity panel
 *
 * @remarks
 * A page of `rows`, newest first. `hasMore` says another page lies beyond
 * it: send the last row's `entryNumber` to read it.
 *
 * @mcp read
 */
export const getItemLedgerActivity = defineServiceFn({
  input: z.looseObject({
    itemId: z.string(),
    locationId: z.string(),
    entryNumber: z.number().optional(),
    direction: z.enum(["older", "newer"]).optional(),
    inclusive: z.boolean().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const page = await utils.getItemLedgerActivity(
      ctx.asCaller.supabase,
      payload(ctx, input).build() as never
    );
    const rows = unwrap(ctx, page);
    if (rows instanceof Error) return rows;
    return { rows, hasMore: page.hasMore };
  }
});

/**
 * On-hand quantity of an item at a location right after ledger entry
 * `entryNumber` (omit it for on-hand now), on the same definition as the
 * inventory table's On Hand column.
 *
 * @mcp read
 */
export const getItemLedgerBalance = defineServiceFn({
  input: z.looseObject({
    itemId: z.string(),
    locationId: z.string(),
    entryNumber: z.number().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getItemLedgerBalance(
        ctx.asCaller.supabase,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get batch properties
 *
 * @mcp read
 */
export const getBatchProperties = defineServiceFn({
  input: z.looseObject({ itemIds: z.array(z.string()) }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getBatchProperties(
        ctx.asCaller.supabase,
        input.itemIds,
        ctx.company.id
      )
    );
  }
});

/**
 * Get inventory items
 *
 * @mcp read
 */
export const getInventoryItems = defineServiceFn({
  input: z.looseObject({
    locationId: z.string(),
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getInventoryItems(
        ctx.asCaller.supabase,
        input.locationId as never,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get inventory valuation
 *
 * @mcp read
 */
export const getInventoryValuation = defineServiceFn({
  input: z.looseObject({
    asOfDate: z.string().nullable().optional(),
    locationId: z.string().nullable().optional()
  }),
  // A valuation is the accounting report's: inventory rights alone see no cost.
  permission: { view: "accounting" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getInventoryValuation(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get inventory valuation tie out
 *
 * @mcp read
 */
export const getInventoryValuationTieOut = defineServiceFn({
  input: z.looseObject({ asOfDate: z.string().nullable().optional() }),
  permission: { view: "accounting" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getInventoryValuationTieOut(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.asOfDate as never
      )
    );
  }
});

/**
 * Creates a draft GL journal that clears the inventory valuation variance
 *
 * @mcp
 */
export const createInventoryReconciliationJournal = defineServiceFn({
  input: z.looseObject({ asOfDate: z.string() }),
  permission: { create: "accounting" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.createInventoryReconciliationJournal(
        ctx.asCaller.supabase,
        ctx.asSystem.pg,
        ctx.company.id,
        payload(ctx, input).withUser().forUpsert() as never
      )
    );
  }
});

/**
 * Get kanbans
 *
 * @mcp read
 */
export const getKanbans = defineServiceFn({
  input: z.looseObject({
    locationId: z.string(),
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getKanbans(
        ctx.asCaller.supabase,
        input.locationId as never,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get kanban
 *
 * @mcp read
 */
export const getKanban = defineServiceFn({
  input: z.looseObject({ kanbanId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getKanban(
        ctx.asCaller.supabase,
        input.kanbanId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get kanban projected quantities
 *
 * @mcp read
 */
export const getKanbanProjectedQuantities = defineServiceFn({
  input: z.looseObject({ kanbanIds: z.array(z.string()) }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getKanbanProjectedQuantities(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.kanbanIds
      )
    );
  }
});

/**
 * Get stock transfer
 *
 * @mcp read
 */
export const getStockTransfer = defineServiceFn({
  input: z.looseObject({ stockTransferId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const transfer = await service.getStockTransfer(
      ctx.asCaller.supabase,
      input.stockTransferId
    );
    if (transfer.data && transfer.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, transfer);
  }
});

/**
 * Get stock transfer lines
 *
 * @mcp read
 */
export const getStockTransferLines = defineServiceFn({
  input: z.looseObject({ stockTransferId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const lines = await service.getStockTransferLines(
      ctx.asCaller.supabase,
      input.stockTransferId
    );
    return unwrap(ctx, {
      ...lines,
      data: lines.data?.filter((line) => line.companyId === ctx.company.id)
    });
  }
});

/**
 * Get stock transfers
 *
 * @mcp read
 */
export const getStockTransfers = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional(),
    locationId: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getStockTransfers(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get receipts
 *
 * @mcp read
 */
export const getReceipts = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getReceipts(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get receipt
 *
 * @mcp read
 */
export const getReceipt = defineServiceFn({
  input: z.looseObject({ receiptId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const receipt = await service.getReceipt(
      ctx.asCaller.supabase,
      input.receiptId
    );
    if (receipt.data && receipt.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, receipt);
  }
});

/**
 * Get receipt lines
 *
 * @mcp read
 */
export const getReceiptLines = defineServiceFn({
  input: z.looseObject({ receiptId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const lines = await service.getReceiptLines(
      ctx.asCaller.supabase,
      input.receiptId
    );
    return unwrap(ctx, {
      ...lines,
      data: lines.data?.filter((line) => line.companyId === ctx.company.id)
    });
  }
});

/**
 * The documents around a receipt that its own row does not name: the purchase
 * invoices raised against its supplier interaction, and, for a customer
 * return, the customer it came back from.
 *
 * @mcp read
 */
export const getReceiptRelatedItems = defineServiceFn({
  input: z.looseObject({
    supplierInteractionId: z.string().nullable(),
    salesReturnOrderId: z.string().nullable()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return await service.getReceiptRelatedItems(
      ctx.asCaller.supabase,
      ctx.company.id,
      input.supplierInteractionId as never,
      input.salesReturnOrderId as never
    );
  }
});

/**
 * Get receipt tracking
 *
 * @mcp read
 */
export const getReceiptTracking = defineServiceFn({
  input: z.looseObject({ receiptId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await utils.getReceiptTracking(
        ctx.asCaller.supabase,
        input.receiptId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get receipt files
 *
 * @remarks
 * The files attached to each receipt line in `lineIds`, at most 200 lines a
 * call.
 *
 * @mcp read
 */
export const getReceiptFiles = defineServiceFn({
  // One storage listing per line.
  input: z.looseObject({ lineIds: z.array(z.string()).max(200) }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getReceiptFiles(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.lineIds
      )
    );
  }
});

/**
 * Get serial numbers for item
 *
 * @mcp read
 */
export const getSerialNumbersForItem = defineServiceFn({
  input: z.looseObject({ itemId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSerialNumbersForItem(
        ctx.asCaller.supabase,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Available tracked entities for an item at a location, one row per entity, with its bin, on-hand, and FEFO/FIFO order keys — for the shared TrackedEntityPicker
 *
 * @mcp read
 */
export const getAvailableTrackedEntities = defineServiceFn({
  input: z.looseObject({
    itemId: z.string(),
    locationId: z.string(),
    excludeLineside: z.boolean().optional(),
    excludeAllocated: z.boolean().optional(),
    excludeLineId: z.string().nullable().optional(),
    inStorageUnit: z.looseObject({ id: z.string().nullable() }).optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getAvailableTrackedEntities(
        ctx.asCaller.supabase,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * The configured tracked-entity pick order for an item at a location, used as the picker's default sort
 *
 * @mcp read
 */
export const getPickOrder = defineServiceFn({
  input: z.looseObject({ itemId: z.string(), locationId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return await service.getPickOrder(
      ctx.asCaller.supabase,
      payload(ctx, input).build() as never
    );
  }
});

/**
 * Get batch numbers for item
 *
 * @mcp read
 */
export const getBatchNumbersForItem = defineServiceFn({
  input: z.looseObject({
    itemId: z.string(),
    isReadOnly: z.boolean().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getBatchNumbersForItem(
        ctx.asCaller.supabase,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get storage units list
 *
 * @mcp read
 */
export const getStorageUnitsList = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "inventory" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getStorageUnitsList(ctx.asCaller.supabase, ctx.company.id)
    );
  }
});

/**
 * Get storage units list for location
 *
 * @mcp read
 */
export const getStorageUnitsListForLocation = defineServiceFn({
  input: z.looseObject({ locationId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getStorageUnitsListForLocation(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.locationId as never
      )
    );
  }
});

/**
 * Get storage units tree for location
 *
 * @mcp read
 */
export const getStorageUnitsTreeForLocation = defineServiceFn({
  input: z.looseObject({ locationId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getStorageUnitsTreeForLocation(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.locationId as never
      )
    );
  }
});

/**
 * Get storage unit
 *
 * @mcp read
 */
export const getStorageUnit = defineServiceFn({
  input: z.looseObject({ storageUnitId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const unit = await service.getStorageUnit(
      ctx.asCaller.supabase,
      input.storageUnitId
    );
    if (unit.data && unit.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, unit);
  }
});

/**
 * Get effective work center id
 *
 * @mcp read
 */
export const getEffectiveWorkCenterId = defineServiceFn({
  input: z.looseObject({ storageUnitId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const owned = await refuseUnlessOwned(ctx, "storageUnit", {
      id: input.storageUnitId
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.getEffectiveWorkCenterId(
        ctx.asCaller.supabase,
        input.storageUnitId as never
      )
    );
  }
});

/**
 * Get storage unit roots
 *
 * @mcp read
 */
export const getStorageUnitRoots = defineServiceFn({
  input: z.looseObject({
    locationId: z.string(),
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getStorageUnitRoots(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.locationId as never,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get storage unit children
 *
 * @mcp read
 */
export const getStorageUnitChildren = defineServiceFn({
  input: z.looseObject({ parentId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const children = await service.getStorageUnitChildren(
      ctx.asCaller.supabase,
      input.parentId
    );
    return unwrap(ctx, {
      ...children,
      data: children.data?.filter((unit) => unit.companyId === ctx.company.id)
    });
  }
});

/**
 * Get storage unit subtrees
 *
 * @mcp read
 */
export const getStorageUnitSubtrees = defineServiceFn({
  input: z.looseObject({
    locationId: z.string(),
    rootIds: z.array(z.string()),
    maxDepth: z.number()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getStorageUnitSubtrees(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.locationId as never,
        input.rootIds,
        input.maxDepth as never
      )
    );
  }
});

/**
 * Get storage unit parent ids with children
 *
 * @mcp read
 */
export const getStorageUnitParentIdsWithChildren = defineServiceFn({
  input: z.looseObject({ locationId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getStorageUnitParentIdsWithChildren(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.locationId as never
      )
    );
  }
});

/**
 * Search storage units with ancestors
 *
 * @mcp read
 */
export const searchStorageUnitsWithAncestors = defineServiceFn({
  input: z.looseObject({ locationId: z.string(), search: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.searchStorageUnitsWithAncestors(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.locationId as never,
        input.search as never
      )
    );
  }
});

/**
 * Get stock movements
 *
 * @mcp read
 */
export const getStockMovements = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getStockMovements(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get shipments
 *
 * @mcp read
 */
export const getShipments = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getShipments(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get shipment
 *
 * @mcp read
 */
export const getShipment = defineServiceFn({
  input: z.looseObject({ shipmentId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const shipment = await service.getShipment(
      ctx.asCaller.supabase,
      input.shipmentId
    );
    if (shipment.data && shipment.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, shipment);
  }
});

/**
 * Get shipment lines
 *
 * @mcp read
 */
export const getShipmentLines = defineServiceFn({
  input: z.looseObject({ shipmentId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const lines = await service.getShipmentLines(
      ctx.asCaller.supabase,
      input.shipmentId
    );
    return unwrap(ctx, {
      ...lines,
      data: lines.data?.filter((line) => line.companyId === ctx.company.id)
    });
  }
});

/**
 * Get shipment related items
 *
 * @mcp read
 */
export const getShipmentRelatedItems = defineServiceFn({
  input: z.looseObject({
    shipmentId: z.string(),
    sourceDocumentId: z.string()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    // The reads below run by these ids alone: both must be this company's
    // shipment and its own source document.
    const owned = await refuseUnlessOwned(
      ctx,
      "shipment",
      input.sourceDocumentId
        ? { id: input.shipmentId, sourceDocumentId: input.sourceDocumentId }
        : { id: input.shipmentId }
    );
    if (owned) return owned;
    return await service.getShipmentRelatedItems(
      ctx.asCaller.supabase,
      input.shipmentId as never,
      input.sourceDocumentId as never
    );
  }
});

/**
 * Get shipment tracking
 *
 * @mcp read
 */
export const getShipmentTracking = defineServiceFn({
  input: z.looseObject({ shipmentId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await utils.getShipmentTracking(
        ctx.asCaller.supabase,
        input.shipmentId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get rental shipment lines
 *
 * @mcp read
 */
export const getRentalShipmentLines = defineServiceFn({
  input: z.looseObject({ shipmentId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getRentalShipmentLines(
        ctx.asCaller.supabase,
        input.shipmentId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get rental receipt lines
 *
 * @mcp read
 */
export const getRentalReceiptLines = defineServiceFn({
  input: z.looseObject({ receiptId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getRentalReceiptLines(
        ctx.asCaller.supabase,
        input.receiptId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get shipping method
 *
 * @mcp read
 */
export const getShippingMethod = defineServiceFn({
  input: z.looseObject({ shippingMethodId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const method = await service.getShippingMethod(
      ctx.asCaller.supabase,
      input.shippingMethodId
    );
    if (method.data && method.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, method);
  }
});

/**
 * Get shipping methods
 *
 * @mcp read
 */
export const getShippingMethods = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getShippingMethods(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get shipping methods list
 *
 * @mcp read
 */
export const getShippingMethodsList = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "inventory" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getShippingMethodsList(
        ctx.asCaller.supabase,
        ctx.company.id
      )
    );
  }
});

/**
 * Get shipping terms list
 *
 * @mcp read
 */
export const getShippingTermsList = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "inventory" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getShippingTermsList(ctx.asCaller.supabase, ctx.company.id)
    );
  }
});

/**
 * Get tracked entities
 *
 * @mcp read
 */
export const getTrackedEntities = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getTrackedEntities(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get tracked entities by make method id
 *
 * @mcp read
 */
export const getTrackedEntitiesByMakeMethodId = defineServiceFn({
  input: z.looseObject({ jobMakeMethodId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getTrackedEntitiesByMakeMethodId(
        ctx.asCaller.supabase,
        input.jobMakeMethodId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get tracked entity
 *
 * @mcp read
 */
export const getTrackedEntity = defineServiceFn({
  input: z.looseObject({ trackedEntityId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const entity = await service.getTrackedEntity(
      ctx.asCaller.supabase,
      input.trackedEntityId
    );
    if (entity.data && entity.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, entity);
  }
});

/**
 * Manual override of a tracked entity's expirationDate
 *
 * @remarks
 * An empty or missing `expirationDate` clears it. The `reason` is kept in the
 * entity's override history.
 *
 * @mcp
 */
export const updateTrackedEntityExpiry = defineServiceFn({
  input: z.looseObject({
    trackedEntityId: z.string(),
    expirationDate: z.string().nullable().optional(),
    reason: z
      .string()
      .min(3, { message: "Reason must be at least 3 characters" })
      .max(500),
    source: z.string().optional()
  }),
  permission: { update: "inventory" },
  async run(ctx, input) {
    const owned = await refuseUnlessOwned(ctx, "trackedEntity", {
      id: input.trackedEntityId
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.updateTrackedEntityExpiry(ctx.asCaller.supabase, {
        trackedEntityId: input.trackedEntityId,
        expirationDate: input.expirationDate || null,
        reason: input.reason,
        source: input.source,
        userId: ctx.auditUserId
      })
    );
  }
});

/**
 * Merge tracked entities into one lot.
 *
 * @remarks
 * Combines two or more Available lots of one item into ONE new lot: their
 * summed quantity, the earliest expiration date and the attributes every lot
 * shares. The merged lots become Consumed, and the new lot's genealogy names
 * each of them. It takes the first lot's number unless `readableId` names one.
 *
 * @mcp
 */
export const mergeTrackedEntities = defineServiceFn({
  input: z.object({
    trackedEntityIds: z.array(z.string()).min(2),
    readableId: z.string().nullable().optional()
  }),
  permission: { update: "inventory" },
  async run(ctx, { trackedEntityIds, readableId }) {
    // As the system: the gate above is the `issue` posting's own rule for a
    // merge, and the posting reads the lots by this company.
    return unwrap(
      ctx,
      await service.mergeTrackedEntities(
        ctx.asSystem.supabase,
        ctx.asSystem.pg,
        {
          trackedEntityIds,
          readableId,
          companyId: ctx.company.id,
          userId: ctx.auditUserId
        }
      )
    );
  }
});

/**
 * Get warehouse transfers
 *
 * @mcp read
 */
export const getWarehouseTransfers = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getWarehouseTransfers(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get warehouse transfer
 *
 * @mcp read
 */
export const getWarehouseTransfer = defineServiceFn({
  input: z.looseObject({ transferId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const transfer = await service.getWarehouseTransfer(
      ctx.asCaller.supabase,
      input.transferId
    );
    if (transfer.data && transfer.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, transfer);
  }
});

/**
 * The documents a warehouse transfer has raised: the shipments that send it out of the source location and the receipts that take it in at the destination
 *
 * @mcp read
 */
export const getWarehouseTransferRelatedItems = defineServiceFn({
  input: z.looseObject({ transferId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return await service.getWarehouseTransferRelatedItems(
      ctx.asCaller.supabase,
      ctx.company.id,
      input.transferId as never
    );
  }
});

/**
 * Get warehouse transfer line
 *
 * @mcp read
 */
export const getWarehouseTransferLine = defineServiceFn({
  input: z.looseObject({ transferId: z.string(), lineId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const line = await service.getWarehouseTransferLine(
      ctx.asCaller.supabase,
      input.transferId,
      input.lineId
    );
    if (line.data && line.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, line);
  }
});

/**
 * Get warehouse transfer lines
 *
 * @mcp read
 */
export const getWarehouseTransferLines = defineServiceFn({
  input: z.looseObject({ transferId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const lines = await service.getWarehouseTransferLines(
      ctx.asCaller.supabase,
      input.transferId
    );
    return unwrap(ctx, {
      ...lines,
      data: lines.data?.filter((line) => line.companyId === ctx.company.id)
    });
  }
});

/**
 * Get stock movement effective quantity
 *
 * @mcp read
 */
export const getStockMovementEffectiveQuantity = defineServiceFn({
  input: z.looseObject({ itemLedgerId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getStockMovementEffectiveQuantity(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.itemLedgerId as never
      )
    );
  }
});

/**
 * Correct stock movement
 *
 * @remarks
 * Books one opposite movement so the posted movement's quantity becomes
 * `correctedQuantity` (signed, as the ledger stores it), dated with the
 * original and posted into its accounting period.
 *
 * @mcp
 */
export const correctStockMovement = defineServiceFn({
  input: service.correctStockMovementInput,
  permission: service.postStockMovementCorrectionPermission,
  async run(ctx, input) {
    const corrected = await run(ctx, "correct-stock-movement", () =>
      service.postStockMovementCorrection(ctx, input)
    );
    return corrected instanceof Error ? corrected : corrected.itemLedger;
  }
});

/**
 * Get inventory counts
 *
 * @mcp read
 */
export const getInventoryCounts = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getInventoryCounts(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get inventory count
 *
 * @mcp read
 */
export const getInventoryCount = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getInventoryCount(
        ctx.asCaller.supabase,
        input.id as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get inventory count lines
 *
 * @mcp read
 */
export const getInventoryCountLines = defineServiceFn({
  input: z.looseObject({
    inventoryCountId: z.string(),
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getInventoryCountLines(
        ctx.asCaller.supabase,
        input.inventoryCountId as never,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get inventory count line summary
 *
 * @mcp read
 */
export const getInventoryCountLineSummary = defineServiceFn({
  input: z.looseObject({ inventoryCountId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return await service.getInventoryCountLineSummary(
      ctx.asCaller.supabase,
      input.inventoryCountId as never,
      ctx.company.id
    );
  }
});

/**
 * Get inventory count movements
 *
 * @mcp read
 */
export const getInventoryCountMovements = defineServiceFn({
  input: z.looseObject({ inventoryCountId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getInventoryCountMovements(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.inventoryCountId as never
      )
    );
  }
});

/**
 * Delete inventory count
 *
 * @mcp destructive
 */
export const deleteInventoryCount = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const count = await service.getInventoryCount(
      ctx.asCaller.supabase,
      input.id,
      ctx.company.id
    );
    if (count.error && count.error.code !== "PGRST116") {
      return ctx.error(
        "internal",
        "Failed to load inventory count",
        count.error
      );
    }
    // A posted count is the record of the adjustments it booked.
    if (count.data?.status === "Posted") {
      return ctx.error(
        "rule",
        "Cannot delete a posted count. Correct its stock movements instead."
      );
    }
    return unwrap(
      ctx,
      await service.deleteInventoryCount(
        ctx.asCaller.supabase,
        input.id as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Update inventory count line
 *
 * @remarks
 * Records the caller's count of one line; leaving out `countedQuantity`
 * clears it. Only a Draft count's lines change.
 *
 * @mcp
 */
export const updateInventoryCountLine = defineServiceFn({
  input: z.object({
    id: z.string().min(1),
    countedQuantity: z.number().min(0).optional()
  }),
  permission: { update: "inventory" },
  async run(ctx, { id, countedQuantity }) {
    const updated = await service.updateInventoryCountLine(ctx.asSystem.pg, {
      id,
      countedQuantity,
      companyId: ctx.company.id,
      countedBy: ctx.auditUserId
    });
    if (!updated) {
      return ctx.error(
        "conflict",
        "Counts can only be edited while the document is Draft"
      );
    }
    return updated;
  }
});

/**
 * Confirm or reopen an inventory count
 *
 * @remarks
 * `Pending` confirms a Draft count for review; `Draft` reopens a Pending one
 * for entry. A count is posted only by `postInventoryCount`, which books its
 * variances; a Posted count stays Posted.
 *
 * @mcp
 */
export const updateInventoryCountStatus = defineServiceFn({
  input: z.object({
    id: z.string(),
    status: z.enum(["Draft", "Pending"])
  }),
  permission: { update: "inventory" },
  async run(ctx, { id, status }) {
    const from = inventoryCountStatusFrom(status);
    const count = await service.getInventoryCount(
      ctx.asCaller.supabase,
      id,
      ctx.company.id
    );
    if (count.error && count.error.code !== "PGRST116") {
      return ctx.error(
        "internal",
        "Failed to load inventory count",
        count.error
      );
    }
    if (!count.data) return ctx.error("notFound", "Inventory count not found");
    if (count.data.status !== from.status) {
      return ctx.error("rule", from.refusal);
    }
    const update = await service.updateInventoryCountStatus(
      ctx.asCaller.supabase,
      {
        id,
        companyId: ctx.company.id,
        status,
        expectedStatus: from.status,
        updatedBy: ctx.auditUserId
      }
    );
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update inventory count status",
        update.error
      );
    }
    return { id, status };
  }
});

/**
 * Update batch property order
 *
 * @mcp
 */
export const updateBatchPropertyOrder = defineServiceFn({
  input: z.looseObject({
    id: z.string().min(1),
    sortOrder: z.number().min(0),
    batchPropertyGroupId: z.string().nullable().optional()
  }),
  permission: { update: "inventory" },
  async run(ctx, input) {
    // The update matches by id alone: it must be this company's property.
    const owned = await refuseUnlessOwned(ctx, "batchProperty", {
      id: input.id
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.updateBatchPropertyOrder(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Upsert batch property
 *
 * @remarks
 * A `list` property needs its `listOptions`; another type keeps none.
 *
 * @mcp
 */
export const upsertBatchProperty = defineServiceFn({
  input: z
    .looseObject({
      id: z.string().optional(),
      itemId: z.string().min(1),
      label: z.string().min(1),
      dataType: z.enum(["text", "numeric", "boolean", "list", "date"]),
      listOptions: z.array(z.string().min(1)).optional(),
      configurationParameterGroupId: z.string().optional()
    })
    .refine((d) => d.dataType !== "list" || !!d.listOptions, {
      message: "List options are required",
      path: ["listOptions"]
    }),
  permission: { update: "inventory" },
  async run(ctx, input) {
    if (input.id) {
      // The update matches by id alone: it must be this company's property.
      const owned = await refuseUnlessOwned(ctx, "batchProperty", {
        id: input.id
      });
      if (owned) return owned;
    }
    return unwrap(
      ctx,
      await service.upsertBatchProperty(
        ctx.asCaller.supabase,
        payload(ctx, {
          ...input,
          listOptions: input.dataType === "list" ? input.listOptions : undefined
        })
          .withUser()
          .for(input.id ? "update" : "create") as never
      )
    );
  }
});

// The kanban form's rules (`kanbanValidator`), for a caller that sends JSON.
const kanbanInput = z
  .looseObject({
    itemId: z.string().min(1),
    replenishmentSystem: z.enum(["Buy", "Make", "Transfer"]),
    autoRelease: z.boolean().optional(),
    autoStartJob: z.boolean().optional(),
    completedBarcodeOverride: z.string().optional(),
    quantity: z.number().int().min(1),
    locationId: z.string().min(1),
    storageUnitId: z.string().optional(),
    fromStorageUnitId: z.string().optional(),
    supplierId: z.string().optional(),
    purchaseUnitOfMeasureCode: z.string().optional(),
    conversionFactor: z
      .number()
      .min(0)
      .describe(
        "1 when left out on create; on update a field left out keeps its value."
      )
      .optional(),
    replenishmentLevel: z.number().min(0).optional(),
    customFields: z.unknown().optional()
  })
  .refine((d) => d.replenishmentSystem !== "Buy" || !!d.supplierId, {
    message: "Supplier is required",
    path: ["supplierId"]
  })
  .refine(
    (d) => d.replenishmentSystem !== "Transfer" || !!d.fromStorageUnitId,
    { message: "From storage unit is required", path: ["fromStorageUnitId"] }
  )
  .refine((d) => d.replenishmentSystem !== "Transfer" || !!d.storageUnitId, {
    message: "To storage unit is required",
    path: ["storageUnitId"]
  })
  .refine(
    (d) =>
      d.replenishmentSystem !== "Transfer" ||
      d.fromStorageUnitId !== d.storageUnitId,
    {
      message: "From and to storage units must be different",
      path: ["storageUnitId"]
    }
  )
  .refine(
    (d) =>
      d.replenishmentSystem === "Transfer" ||
      d.replenishmentLevel === undefined,
    {
      message: "Only a transfer kanban can have a replenishment level",
      path: ["replenishmentLevel"]
    }
  );

/**
 * Create a kanban
 *
 * @remarks
 * A Buy kanban needs its supplier; a Transfer kanban needs a from and a to
 * storage unit, and only it can have a replenishment level. When the
 * location's Kanbans printer auto-prints, the new kanban's Create card is
 * printed.
 *
 * @mcp
 */
export const createKanban = defineServiceFn({
  input: kanbanInput,
  permission: { create: "inventory" },
  async run(ctx, { id: _id, ...input }) {
    const created = unwrap(
      ctx,
      await service.upsertKanban(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
    if (created instanceof CarbonError || !created) return created;

    await service.autoPrint(ctx, {
      sourceDocument: "Kanban",
      sourceDocumentId: created.id,
      locationId: input.locationId,
      context: "kanban"
    });

    return created;
  }
});

/**
 * Update a kanban
 *
 * @remarks
 * The same rules as `createKanban`.
 *
 * @mcp
 */
export const updateKanban = defineServiceFn({
  input: kanbanInput.extend({
    id: z.string().describe("The kanban to update.")
  }),
  permission: { update: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertKanban(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Create a storage unit
 *
 * @remarks
 * Upsert storage unit
 *
 * @mcp
 */
export const createStorageUnit = defineServiceFn({
  input: z.looseObject({
    name: z.string().min(1),
    locationId: z.string().min(1),
    warehouseId: z.string().optional(),
    parentId: z.string().optional(),
    workCenterId: z.string().optional(),
    storageTypeIds: z.array(z.string()).optional(),
    customFields: z.unknown().optional()
  }),
  permission: { create: "inventory" },
  async run(ctx, { id: _id, ...input }) {
    return unwrap(
      ctx,
      await service.upsertStorageUnit(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a storage unit
 *
 * @remarks
 * Upsert storage unit
 *
 * @mcp
 */
export const updateStorageUnit = defineServiceFn({
  input: z
    .looseObject({
      name: z.string().min(1),
      locationId: z.string().min(1),
      warehouseId: z.string().optional(),
      parentId: z.string().optional(),
      workCenterId: z.string().optional(),
      storageTypeIds: z.array(z.string()).optional(),
      customFields: z.unknown().optional(),
      id: z.string().describe("The storage unit to update.").optional()
    })
    .required({ id: true }),
  permission: { update: "inventory" },
  async run(ctx, input) {
    // The update matches by id alone: it must be this company's unit.
    const owned = await refuseUnlessOwned(ctx, "storageUnit", {
      id: input.id
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.upsertStorageUnit(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Create a shipping method
 *
 * @remarks
 * Upsert shipping method
 *
 * @mcp
 */
export const createShippingMethod = defineServiceFn({
  input: z.looseObject({
    name: z.string().min(1),
    carrier: z.enum(["UPS", "FedEx", "USPS", "DHL", "Other"]),
    carrierAccountId: z.string().optional(),
    trackingUrl: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { create: "inventory" },
  async run(ctx, { id: _id, ...input }) {
    return unwrap(
      ctx,
      await service.upsertShippingMethod(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a shipping method
 *
 * @remarks
 * Upsert shipping method
 *
 * @mcp
 */
export const updateShippingMethod = defineServiceFn({
  input: z
    .looseObject({
      name: z.string().min(1),
      carrier: z.enum(["UPS", "FedEx", "USPS", "DHL", "Other"]),
      carrierAccountId: z.string().optional(),
      trackingUrl: z.string().optional(),
      customFields: z.unknown().optional(),
      id: z.string().describe("The shipping method to update.").optional()
    })
    .required({ id: true }),
  permission: { update: "inventory" },
  async run(ctx, input) {
    // The update matches by id alone: it must be this company's method.
    const owned = await refuseUnlessOwned(ctx, "shippingMethod", {
      id: input.id
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.upsertShippingMethod(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Create a stock transfer line
 *
 * @remarks
 * Adds a line to a Draft stock transfer: reopen a locked one first. The line
 * starts unpicked; picking moves stock through `pickStockTransferLine`.
 *
 * @mcp
 */
export const createStockTransferLine = defineServiceFn({
  input: z.object({
    stockTransferId: z.string().min(1),
    itemId: z.string().min(1),
    fromStorageUnitId: z.string().optional(),
    toStorageUnitId: z.string().optional(),
    quantity: z.number().min(0),
    requiresBatchTracking: booleanField(),
    requiresSerialTracking: booleanField()
  }),
  permission: { create: "inventory" },
  async run(ctx, input) {
    const transfer = await service.unlockedStockTransfer(
      ctx,
      input.stockTransferId
    );
    if (transfer instanceof Error) return transfer;
    return unwrap(
      ctx,
      await service.upsertStockTransferLine(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a stock transfer line
 *
 * @remarks
 * Changes a line of a Draft stock transfer: reopen a locked one first. Its
 * picked quantity moves only by picking (`pickStockTransferLine`).
 *
 * @mcp
 */
export const updateStockTransferLine = defineServiceFn({
  input: z
    .object({
      stockTransferId: z.string().min(1),
      itemId: z.string().min(1),
      fromStorageUnitId: z.string().optional(),
      toStorageUnitId: z.string().optional(),
      quantity: z.number().min(0),
      requiresBatchTracking: booleanField(),
      requiresSerialTracking: booleanField(),
      id: z.string().describe("The line to update.").optional()
    })
    .required({ id: true }),
  permission: { create: "inventory", update: "inventory" },
  async run(ctx, input) {
    const transfer = await service.unlockedStockTransfer(
      ctx,
      input.stockTransferId
    );
    if (transfer instanceof Error) return transfer;
    // The line must already be on this transfer: an update cannot move it
    // off a locked one.
    const line = await ctx.asCaller.supabase
      .from("stockTransferLine")
      .select("id")
      .eq("id", input.id)
      .eq("stockTransferId", input.stockTransferId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (line.error) {
      return ctx.error(
        "internal",
        "Failed to load stock transfer line",
        line.error
      );
    }
    if (!line.data) {
      return ctx.error("notFound", "Stock transfer line not found");
    }
    return unwrap(
      ctx,
      await service.upsertStockTransferLine(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Get storage unit descendants
 *
 * @mcp read
 */
export const getStorageUnitDescendants = defineServiceFn({
  input: z.looseObject({ storageUnitId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const descendants = await service.getStorageUnitDescendants(
      ctx.asCaller.supabase,
      input.storageUnitId
    );
    return unwrap(ctx, {
      ...descendants,
      data: descendants.data?.filter(
        (unit) => unit.companyId === ctx.company.id
      )
    });
  }
});

/**
 * Expand storage unit ids with descendants
 *
 * @mcp read
 */
export const expandStorageUnitIdsWithDescendants = defineServiceFn({
  input: z.looseObject({ storageUnitIds: z.array(z.string()) }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return await service.expandStorageUnitIdsWithDescendants(
      ctx.asCaller.supabase,
      input.storageUnitIds
    );
  }
});

/**
 * Get storage type usage
 *
 * @mcp read
 */
export const getStorageTypeUsage = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { view: "parts" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getStorageTypeUsage(
        ctx.asCaller.supabase,
        input.id as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Delete storage type with cascade
 *
 * @remarks
 * A storage type that storage units still have is deleted only with
 * `cascade`, which takes it off those units in the same transaction.
 *
 * @mcp destructive
 */
export const deleteStorageTypeWithCascade = defineServiceFn({
  input: z.looseObject({ id: z.string(), cascade: z.boolean().optional() }),
  permission: { delete: "parts" },
  async run(ctx, { id, cascade }) {
    const usage = await service.getStorageTypeUsage(
      ctx.asCaller.supabase,
      id,
      ctx.company.id
    );
    if (usage.error) {
      return ctx.error(
        "internal",
        "Failed to load storage type usage",
        usage.error
      );
    }
    if (usage.count) {
      if (!cascade) {
        return ctx.error(
          "rule",
          "Storage type is in use; confirm cascade to delete"
        );
      }
      // The cascade edits those storage units.
      if (!ctx.can({ update: "parts" })) {
        return ctx.error("forbidden", "You do not have permission to do this");
      }
    }
    await service.deleteStorageTypeWithCascade(
      ctx.asSystem.pg,
      id,
      ctx.company.id
    );
    return { id };
  }
});

/**
 * Get storage types
 *
 * @mcp read
 */
export const getStorageTypes = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "parts" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getStorageTypes(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get storage type
 *
 * @mcp read
 */
export const getStorageType = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { view: "parts" },
  async run(ctx, input) {
    const storageType = await service.getStorageType(
      ctx.asCaller.supabase,
      input.id
    );
    if (storageType.data && storageType.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, storageType);
  }
});

/**
 * Get storage types list
 *
 * @mcp read
 */
export const getStorageTypesList = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "inventory" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getStorageTypesList(ctx.asCaller.supabase, ctx.company.id)
    );
  }
});

/**
 * Create a storage type
 *
 * @remarks
 * Upsert storage type
 *
 * @mcp
 */
export const createStorageType = defineServiceFn({
  input: z.looseObject({
    name: z.string().min(1),
    customFields: z.unknown().optional()
  }),
  permission: { create: "parts" },
  async run(ctx, { id: _id, ...input }) {
    return unwrap(
      ctx,
      await service.upsertStorageType(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a storage type
 *
 * @remarks
 * Upsert storage type
 *
 * @mcp
 */
export const updateStorageType = defineServiceFn({
  input: z
    .looseObject({
      name: z.string().min(1),
      customFields: z.unknown().optional(),
      id: z.string().describe("The storage type to update.").optional()
    })
    .required({ id: true }),
  permission: { update: "parts" },
  async run(ctx, input) {
    // The update matches by id alone: it must be this company's type.
    const owned = await refuseUnlessOwned(ctx, "storageType", {
      id: input.id
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.upsertStorageType(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Get shelf life for items
 *
 * @mcp read
 */
export const getShelfLifeForItems = defineServiceFn({
  input: z.looseObject({ itemIds: z.array(z.string()) }),
  permission: { view: "inventory" },
  async run(ctx, { itemIds }) {
    if (itemIds.length === 0) return [];
    return unwrap(
      ctx,
      await ctx.asCaller.supabase
        .from("itemShelfLife")
        .select("itemId, mode, days")
        .in("itemId", itemIds)
        .eq("companyId", ctx.company.id)
    );
  }
});

/**
 * Map of trackedEntityId → expirationDate (or null) for a set of ids
 *
 * @mcp read
 */
export const getTrackedEntityExpirations = defineServiceFn({
  input: z.looseObject({ trackedEntityIds: z.array(z.string()) }),
  permission: { view: "inventory" },
  async run(ctx, { trackedEntityIds }) {
    if (trackedEntityIds.length === 0) {
      return {} as Record<string, string | null>;
    }
    const entities = await ctx.asCaller.supabase
      .from("trackedEntity")
      .select("id, expirationDate")
      .in("id", trackedEntityIds)
      .eq("companyId", ctx.company.id);
    if (entities.error) {
      return ctx.error(
        "internal",
        "Failed to load expiration dates",
        entities.error
      );
    }
    return Object.fromEntries(
      entities.data.map((entity) => [entity.id, entity.expirationDate ?? null])
    ) as Record<string, string | null>;
  }
});

/**
 * Get picking lists
 *
 * @mcp read
 */
export const getPickingLists = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional(),
    status: z.string().nullable().optional(),
    assignee: z.string().nullable().optional(),
    locationId: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getPickingLists(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get picking list
 *
 * @mcp read
 */
export const getPickingList = defineServiceFn({
  input: z.looseObject({ pickingListId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const list = await service.getPickingList(
      ctx.asCaller.supabase,
      input.pickingListId
    );
    if (list.data && list.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, list);
  }
});

/**
 * Get picks by job material
 *
 * @mcp read
 */
export const getPicksByJobMaterial = defineServiceFn({
  input: z.looseObject({ jobId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPicksByJobMaterial(
        ctx.asCaller.supabase,
        input.jobId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get picking list lines
 *
 * @mcp read
 */
export const getPickingListLines = defineServiceFn({
  input: z.looseObject({ pickingListId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const lines = await service.getPickingListLines(
      ctx.asCaller.supabase,
      input.pickingListId
    );
    return unwrap(ctx, {
      ...lines,
      data: lines.data?.filter((line) => line.companyId === ctx.company.id)
    });
  }
});

/**
 * The documents around a picking list that its own row doesn't name: the jobs its lines pick for, with their status
 *
 * @mcp read
 */
export const getPickingListRelatedItems = defineServiceFn({
  input: z.looseObject({ pickingListId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return await service.getPickingListRelatedItems(
      ctx.asCaller.supabase,
      ctx.company.id,
      input.pickingListId as never
    );
  }
});

/**
 * Warehouse on-hand for each line of a picking list: every bin but lineside,
 * the unassigned bin included, keyed by picking list line id.
 *
 * @mcp read
 */
export const getPickingListAvailability = defineServiceFn({
  input: z.looseObject({ pickingListId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const owned = await refuseUnlessOwned(ctx, "pickingList", {
      id: input.pickingListId
    });
    if (owned) return owned;
    return await service.getPickingListAvailability(
      ctx.asCaller.supabase,
      input.pickingListId as never
    );
  }
});

/**
 * The recommended tracked entities (serial/batch lots) for each tracked picking line, in pick order — surfaced as at-a-glance subtext before the picker opens
 *
 * @mcp read
 */
export const getPickingListRecommendations = defineServiceFn({
  input: z.looseObject({ pickingListId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const owned = await refuseUnlessOwned(ctx, "pickingList", {
      id: input.pickingListId
    });
    if (owned) return owned;
    return await service.getPickingListRecommendations(
      ctx.asCaller.supabase,
      input.pickingListId as never
    );
  }
});

/**
 * Get picking list line
 *
 * @mcp read
 */
export const getPickingListLine = defineServiceFn({
  input: z.looseObject({ lineId: z.string() }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    const line = await service.getPickingListLine(
      ctx.asCaller.supabase,
      input.lineId
    );
    if (line.data && line.data.companyId !== ctx.company.id) {
      return ctx.error("notFound", NOT_FOUND);
    }
    return unwrap(ctx, line);
  }
});

/**
 * Delete picking list
 *
 * @mcp destructive
 */
export const deletePickingList = defineServiceFn({
  input: z.looseObject({ pickingListId: z.string() }),
  permission: { delete: "inventory" },
  async run(ctx, input) {
    const owned = await refuseUnlessOwned(ctx, "pickingList", {
      id: input.pickingListId
    });
    if (owned) return owned;
    return unwrap(
      ctx,
      await service.deletePickingList(
        ctx.asCaller.supabase,
        input.pickingListId as never
      )
    );
  }
});

/**
 * Get picking schedule
 *
 * @mcp read
 */
export const getPickingSchedule = defineServiceFn({
  input: z.looseObject({
    locationId: z.string(),
    search: z.string().nullable().optional()
  }),
  permission: { view: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPickingSchedule(
        ctx.asCaller.supabase,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Generate picking list
 *
 * @mcp destructive
 */
export const generatePickingList = defineServiceFn({
  input: z.looseObject({
    jobOperationIds: z.array(z.string()),
    locationId: z.string(),
    assignee: z.string().nullable().optional(),
    dueDate: z.string().nullable().optional()
  }),
  permission: { create: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.generatePickingList(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpsert() as never
      )
    );
  }
});

/**
 * Create a warehouse transfer between locations
 *
 * @remarks
 * Create a Draft warehouse transfer between locations. Generates sequence ID
 * automatically. Its status moves only through `setWarehouseTransferStatus`.
 *
 * @mcp
 */
export const insertWarehouseTransfer = defineServiceFn({
  input: z.object({
    fromLocationId: z.string(),
    toLocationId: z.string(),
    transferId: z.string().optional(),
    transferDate: z.string().optional(),
    expectedReceiptDate: z.string().optional(),
    notes: z.string().optional(),
    reference: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { create: "inventory" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.insertWarehouseTransfer(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpsert() as never
      )
    );
  }
});

/**
 * Update an existing warehouse transfer
 *
 * @remarks
 * Only a Draft transfer's header changes: reopen it first. Its status moves
 * only through `setWarehouseTransferStatus`.
 *
 * @mcp
 */
export const updateWarehouseTransfer = defineServiceFn({
  input: z.object({
    id: z.string(),
    fromLocationId: z.string().optional(),
    toLocationId: z.string().optional(),
    transferId: z.string().optional(),
    transferDate: z.string().optional(),
    expectedReceiptDate: z.string().optional(),
    notes: z.string().optional(),
    reference: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { update: "inventory" },
  async run(ctx, input) {
    const transfer = await service.unlockedWarehouseTransfer(ctx, input.id);
    if (transfer instanceof Error) return transfer;
    return unwrap(
      ctx,
      await service.updateWarehouseTransfer(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Value an item's serial units on hand.
 *
 * @remarks
 * What each serial unit of the item on hand would leave stock at, valued the
 * way a shipment or a capitalization relieves it, keyed by tracked entity id.
 * With `locationId`, only the units at that location.
 *
 * @mcp read
 */
export const getSerialUnitCosts = defineServiceFn({
  input: service.previewSerialUnitCostsInput,
  permission: service.previewSerialUnitCostsPermission,
  async run(ctx, input) {
    return run(ctx, "preview-serial-unit-costs", () =>
      service.previewSerialUnitCosts(ctx, input)
    );
  }
});

/**
 * Recost one serial unit in stock.
 *
 * @remarks
 * Re-books the unit's cost layer at `unitCost` and posts the difference
 * against the offset account. The unit must be the only one of its serial on
 * hand at one location, of a FIFO or LIFO item.
 *
 * @mcp
 */
export const recostSerialUnit = defineServiceFn({
  input: service.recostSerialUnitInput,
  permission: service.recostSerialUnitPermission,
  async run(ctx, input) {
    return run(ctx, "recost-serial-unit", () =>
      service.recostSerialUnit(ctx, input)
    );
  }
});