Transfer Order Automation — Daily Overflow → Sydney Replenishment

What is deployed and what is documented are two different code bases.

Two consequences worth stating plainly:

• The production config cannot run steps 2–3 even if merged. config/production.mjs still carries placeholder script ids for the Create-TO and dropdown RESTlets. The three production saved-search ids are set; the RESTlet ids are not.
• The NetSuite-side scripts are deployed by hand and their state is not tracked in the repo. The branch adds fields to the write script that require a redeploy to take effect (see TO-D5).

What it reads, and where from.

Three NetSuite saved searches, fetched sequentially — they are too large to route through the internal request queue, so parallel fetching risks request-limit errors.

Search 7898 could not be fetched live — the integration role lacks Bin record access. Its committed capture was generated from an admin CSV export as a best-effort stand-in.

What it does with that, step by step.

Traces LI-BL-INV-001 and LI-BL-INV-002.

on daily schedule:
  read search 1 (demand), search 2 (bins), search 3 (open TOs)
  for each item in search 1:
    net demand = QtyDemand as returned          (no subtraction applied)
    if net demand <= 0                     -> skip the item

    available(source) = sum of that source's bins - allocation charged to it
    allocation is consumed Overflow-first, spilling into Bonded if it exceeds the Overflow pool

    to source N units at one source:
      if any single bin holds >= N         -> take the SMALLEST such bin, whole
      else repeat until covered or dry:
        if a remaining bin covers the rest -> take the smallest such bin, whole
        else                               -> take the largest remaining bin, whole
      cap the total taken at available(source)

The original rule (BR-02) computed net = gross − coverage, coverage being the quantity on open Transfer Orders. The code no longer does this — as of commit d68b33f ("NSSS is authoritative: remove code-side TO netting"), search #1's QtyDemand is used directly. Open TOs are read only to find amendable ones. Protection against re-ordering the same stock now rests entirely on the itemallocated supply guard — see TO-D2.

Selection is by quantity only. Bin identity, receipt date and FIFO play no part, because the bin is never recorded on the Transfer Order (BR-13 supersedes the FIFO reading of BR-10). Verified against a real Transfer Order record, whose inventory-detail flag was not set.

The availability cap is applied after the whole-bin pick, so when availability is tighter than the bin, a partial bin moves. A deliberate safety guard, but a deviation from BR-04's literal "move the entire bin".

What it does with that, step by step.

Traces LI-BL-INV-003.

for each source, Overflow before Bonded:
  if nothing left to cover -> stop
  source as much as that lane's availability allows
  emit a line tagged with that source
  carry any remainder to the next lane

The lead time is written as the TO's lead-time override, which drives its expected due date.

Open: the 15 CBM cap is a local truck limit. A Bonded movement is a sea container and its real cap is unconfirmed — 15 is assumed for now, which would wrongly chop a Bonded shipment into 15 CBM pieces. Only bites once a Bonded-sourced item is backordered.

What it does with that, step by step.

Traces LI-BL-FUL-004 and LI-BL-FRT-002. Cap = 15 CBM, the Metro Transfer truck capacity. It is a planning threshold only — no ship method is written to the Transfer Order.

for each line (already tagged with its source):
  if line volume > cap:
    units per TO = floor(cap / item CBM)
    open a fresh TO per chunk until the quantity is exhausted
    force the next same-source line onto a new TO
  else:
    eligible = open TOs that are Pending Approval, share this source, and have room
    1. eligible TO already carrying this item -> add the quantity there
    2. else one eligible TO with room         -> add to the tightest fit
    3. else two eligible TOs with room        -> split across those two
    4. else                                   -> start a new TO

Amendability keys off the custom Transfer Order Approval marker, not the main order status. The automation sets it to Pending Approval on every TO it creates; the team clears it once the order is handled, which locks it. The write script refuses to amend a locked TO, returning TO_LOCKED.

Not implemented: BR-09 re-solve — replacing a previous selection for an item and releasing it back to the pool. The write path only appends and increments. "Never reduce" (BR-07) therefore holds; "re-solve replaces" does not.

The same logic as a path through the decisions, in the order they run.

Read the deployment state first. This tree describes the allocation engine on BE-3412-APPLY-BUSINESS-LOGIC. main carries step 1 only — the decision step returns an empty payload and the write step is commented out — so on the state this entry records, none of the branches below run in production. TO-D9 then found that a commit on main claims to be that engine, without the code being re-verified. Until someone re-reads it, treat this tree as what the engine decides, not as what happened last night.

Four stages, in the order they run: how much · from where · which bins · which Transfer Order. Every branch names the rule it implements, and where an open defect changes what actually happens the branch says so and names it — the tree follows the code, not the spec, and TO-D7 records that the two have drifted apart.

Stage 1 — how much does Sydney need? LI-BL-INV-001

each item in the Sydney backorder search
 ├─ net demand = QtyDemand, EXACTLY AS RETURNED
 │     ⚠ TO-D1: the engine reads the item id as `item_id`; the committed capture
 │       spells it `item_ID`. Every item then resolves to undefined, finds no bins
 │       and is reported as a total shortfall — with no error anywhere. A run that
 │       hits this is indistinguishable from "Overflow is empty"
 │
 │     the spec said net = gross − what is already on open Transfer Orders.
 │     The code stopped doing that at `d68b33f` — the saved search is treated as
 │     authoritative. Open TOs are now read ONLY to find amendable ones      TO-D7
 │
 ├─ net demand ≤ 0 ?  ──► skip the item entirely
 └─ net demand > 0    ──► go to stage 2

Nothing else prevents the same stock being transferred every night. With the netting gone, the only guard left is the itemallocated supply figure — and it is absent from the committed capture of the bin search, so it has never been seen working. TO-D2

Stage 2 — which warehouse supplies it? LI-BL-INV-003

Two lanes, always in this order, and never on the same Transfer Order: one order carries one source and one lead time, and 7 days against 42 is not a detail.

 ├─ 1. OVERFLOW (location 23) ──► drain first · lead time 7 days
 │        available = its bins − the allocation charged to it
 │        allocation is consumed Overflow-first, spilling into Bonded
 │        only once the Overflow pool is exhausted
 │
 ├─ 2. BONDED WH VIETNAM (location 25) ──► the remainder only · lead time 42 days
 │        7 to departure + 28 in transit + 7 buffer
 │
 ├─ nothing left to cover ?  ──► stop; later lanes are not tried
 └─ still short after both ? ──► move everything available anyway,
                                 and email the planner the gap          LI-BL-INV-004

Destination is always Sydney (location 11). The lead time is written as the Transfer Order's lead-time override, which is what drives its expected due date.

Stage 3 — which bins, and how many units? LI-BL-INV-002

Quantities only. The bin is never written onto the Transfer Order — the warehouse picks the physical bin at fulfilment — so bin identity, receipt date and FIFO play no part in the choice. This was verified against a real Transfer Order record, whose inventory-detail flag was not set; TO-D8 records that main's README still says the opposite, so the README is the thing that is wrong here.

to source N units at one lane
 ├─ any single bin holds ≥ N ?
 │    └─ take the SMALLEST such bin, WHOLE                               LI-BL-INV-002
 │       leaves the bulk bins intact for larger jobs later
 └─ no single bin covers it — repeat until covered or dry:
      ├─ a remaining bin covers the rest ? ──► take the smallest such bin, whole
      └─ otherwise                        ──► take the largest remaining bin, whole

 then cap the total taken at that lane's availability
   ⚠ the cap is applied AFTER the whole-bin pick, so when availability is tighter
     than the bin a PARTIAL bin moves. A deliberate safety guard, and a deviation
     from the rule's literal "move the entire bin"

Sydney receives more than it was short, on purpose. Short 2 against a bin of 4 moves all 4. That surplus is intended and is not an error.

Stage 4 — which Transfer Order does the line go on? LI-BL-FUL-004, LI-BL-FRT-002

Cap = 15 CBM, one Metro Transfer truckload. It is a planning threshold only — no ship method is written. The over-cap split is tested first, because a line that cannot fit a truck can never be added to one.

each line, already tagged with its source
 ├─ line volume > 15 CBM ?
 │    └─ units per TO = floor(15 / item CBM)
 │       open a fresh TO per chunk until the quantity is exhausted, and
 │       force the next same-source line onto a new TO
 │       ⚠ TO-D4: a SINGLE unit bigger than 15 CBM makes that floor 0, and the
 │         line is emitted on a Transfer Order over the cap, silently
 │
 └─ otherwise, look for an open Transfer Order to amend
      eligible = Pending Approval · same source · has room
        ⚠ TO-D3: eligibility never checks the DESTINATION, so a TO heading
          somewhere other than Sydney can be selected
        ⚠ TO-D5: "amendable" is decided in two places that do not agree
        ⚠ TO-D6: the engine auto-approves what it creates, which conflicts with
          the amendability model it then relies on
      ├─ 1. an eligible TO already carries this item ──► add to THAT line
      ├─ 2. else one eligible TO with room           ──► add to the tightest fit
      ├─ 3. else two eligible TOs with room          ──► split across those two
      └─ 4. else (or it would take three or more)    ──► raise a NEW Transfer Order

Nothing is ever taken back. Demand dropping after a Transfer Order exists leaves its lines untouched, and re-solve — replacing an earlier selection and releasing it to the pool — is not implemented: the write path only appends and increments. TO-D7

A handled order is locked. Amendability keys off the custom Transfer Order Approval marker, not the order status. The automation sets it to Pending Approval on everything it creates; the team clears it once the order is handled, and the write script then refuses to amend it, returning TO_LOCKED. An amend that would breach the cap returns CBM_CAP_EXCEEDED and writes nothing — that line falls to a new Transfer Order on the next run.

What a run leaves behind

A Transfer Order is a plan, not a movement. It sits awaiting approval until a person approves it. And CBM is deliberately not written on create — NetSuite derives both line and header CBM from the item record. The engine computes it only to size shipments against the cap.

What it writes, and who reads it afterwards.

Created TO headers carry: source location 23 or 25 (never mixed on one TO), destination 11, order status A — NetSuite forces this on create regardless — the approval marker, the lead-time override, and the run date in US MM/DD/YYYY format, since ISO dates fail the save. Lines carry item and quantity only — no bin, no cartons, no units. CBM is deliberately not written on create: NetSuite derives both line and header CBM from the item record. The engine still computes CBM internally, purely to size shipments against the cap.

Real records carried end to end, so the logic can be checked against something that happened.

Traced against the reference captures committed in the repo, with the allocation engine from 47c0845 run over them read-only. Six backordered items, all sourced from Overflow, no open Sydney TO to amend.

Result: one Transfer Order — Overflow 23 → Sydney 11, six lines, 8.83089 CBM (well under the cap, so no split), Pending Approval, 7-day lead time. Plus one shortfall alert: Palermo needed 7, moved 4, short 3.

Note the shape of it: Sydney was short 15 units in total and receives 27, because five of the six lines move a whole bin. That is the rule working as designed, and it is the single behaviour most likely to surprise the warehouse.

What to run to know the behaviour is intact. Expected values, never “should work”.

Acceptance tests for each rule.

Environment. The config auto-selects from the Lambda alias — $LATEST or a local run resolves to staging, which points at the NetSuite sandbox, with no code change between environments. Start read-only: the GET-NSSS harness fetches the three searches and prints row counts and a sample row, and is safe against production. Then the full-engine dry run computes payloads without writing. Only then the create/amend harnesses, which ⚠️ create and amend real Transfer Orders in the sandbox. Verify in NetSuite: source and destination locations, order status, approval marker, lead-time override and expected due date, one line per item with the right quantity, header CBM derived by NetSuite, and no bin/inventory detail set.

What a person checks, by hand, before it is trusted.

How the business signs this off. The Result column below doubles as the sign-off sheet — tick each row against a sandbox run and record who ticked it, following the environment steps above.

UAT sign-off

• ☐ Ran the read-only dry run over live search data before any write
• ☐ Column names (A5) and itemallocated (B6) verified against live responses
• ☐ Bin sourcing (B) — closest-fit, whole-bin and multi-bin all behave as specified
• ☐ Source lanes (C) — Overflow drained first; lanes never share a TO
• ☐ Placement (E) — E7 destination check passes
• ☐ CBM cap (F) — including the oversized-unit case
• ☐ Write mechanics (G) — sandbox TO inspected field by field
• ☐ Sign-off: name & date ____________________

The inputs that sit at the boundary, and whether each is handled.

What breaks it, how that shows, and how to recover.

Scope that was deliberately chosen. A limitation is a decision.

Deliberate scope, not mistakes — the misreadings in What people get wrong above are the business- facing version of the same list. Keeping them here stops them being re-raised as bugs.

Where it does something other than what was decided. A defect is a mistake.

Findings from reading the repository at 807826a (main) and 47c0845 (branch). Each was reproduced against the committed reference data unless noted.

TO-D1 · Saved-search column name mismatch — silently produces zero TOs 🔴

The engine reads the backorder item id as item_id; the committed reference capture returns it as item_ID. Running the branch engine over the committed captures unchanged, every one of the six items resolves to an undefined item, finds no bins, and is reported as a total shortfall — zero Transfer Orders created, and a shortfall email listing every backordered item. Correcting the key alone produces the correct result in the worked example above.

There is no error and no exception: the failure looks exactly like "Overflow is empty". Whether it bites in production depends on which spelling the live search returns — unverifiable from the repository, and the captures are the only committed evidence. Confirm the live column name, and make an unresolved item id a hard error rather than a shortfall.

TO-D2 · Anti-double-order protection rests on one un-captured field 🔴

With demand netting removed, the only thing preventing the same stock being transferred every night is the supply guard's itemallocated field. That field is absent from the committed capture of the bin search, and the code defaults a missing value to zero — meaning "nothing is allocated", so the full bin becomes available again on the next run.

The confirmed label makes this worse, not better. The field's recorded label is "Qty allocated from sales order" — allocated to sales orders. The code uses the value as stock already on open transfer orders. Those are different quantities, and the supply guard is only correct under the second reading. If the label is right, the guard is subtracting the wrong number and the whole anti-double-order argument fails. Resolve which it is before this merges — this now blocks the branch, not just flags it.

Compounding it: the bin search could not be fetched live at all, and its capture was generated from a CSV. The field now carrying the entire idempotency guarantee has never been observed in a live response. Verify it exists and is populated before this is merged; treat its absence as a hard failure, not a zero.

TO-D3 · Amend eligibility never checks the destination 🔴

The spec defines an eligible TO as "open TO, Overflow → Sydney, Pending Approval, with room". The code checks the source and the approval marker — never the destination. Any Pending-Approval TO sourced from Overflow qualifies, wherever it is going.

Not hypothetical: the committed capture of the open-TO search contains a live Overflow TO whose destination is Gold Coast Showroom - Miami. Re-running the engine with that TO marked Pending Approval — the state the search was widened to surface — placed all six of Sydney's replenishment lines onto the Gold Coast shipment and created no Sydney TO at all.

Today it is masked, because the captured TO is Pending Fulfilment and so filtered out. Once the search reliably surfaces Pending-Approval rows, the mask is gone. Add an explicit destination check in the code; don't rely on the saved search to enforce it.

TO-D4 · Oversized single unit escapes the CBM cap 🟠

In the over-cap split, units-per-TO is floored and then raised to a minimum of one. If one unit of an item exceeds 15 CBM, a Transfer Order is created over the cap, silently. Rare, but sofas and modular pieces are the plausible candidates. Flag it as an exception rather than emitting an over-cap TO.

TO-D5 · Two competing definitions of "amendable" 🟠

Amendability is decided in two places that read different fields: the engine picks amend targets by matching the text "Pending Approval" in the open-TO search's approval-status column, while the write script's guard checks the custbody_to_approval field equals 1.

Confirming the labels narrows this: the search column and the custom field carry the same label, Transfer Order Approval, so they are almost certainly two reads of one field rather than two different fields. That removes the risk of them describing different things — but not the mismatch in how they are read, since one matches display text and the other compares a stored value. They can still disagree, and a disagreement is only discovered at write time as a TO_LOCKED failure. The guard also depends on a manual redeploy — the spec flags "redeploy required" twice. Against an older deployed script the guard simply doesn't exist, and any TO can be amended.

TO-D6 · Auto-approve conflicts with the amendability model 🟠

Created TOs are immediately auto-approved to Pending Fulfilment, because that state commits the source stock and makes the searches self-correct. But BR-11 says a TO is amendable only while Pending Approval. The approval marker is still set to Pending Approval on those same TOs, so the guard would permit an amend to a TO that NetSuite has already locked. The repo carries a test harness written specifically to probe whether a Pending-Fulfilment TO can be amended — i.e. this was known to be unresolved. Confirm the intended end state: auto-approve for commitment, or stay amendable. It cannot be both.

TO-D7 · The spec and the code have drifted apart 🟡

The spec is the artefact a reviewer would reach for first, which makes the drift costlier than it looks.

TO-D8 · Merged docs contradict a verified finding 🟡

main's README and netsuite/README.md still state that bins/inventory-detail are required and that the save will fail without them, and the write-step comment gives bin management as the reason for choosing a RESTlet. The branch (and PR #2) record the opposite, verified against a real record: inventory detail is not set, and the warehouse assigns bins at fulfilment. Documentation-only, but it is the currently-merged version that a new reader sees.

Other things to watch

• No test gate before production. npm test exits non-zero by design, and the deploy workflow pushes to the production alias on merge to main with no test step.
• Remaining room on an existing TO is trusted from the search's header CBM total. If that value is stale or absent, room is computed as the full cap and the TO can be over-filled.
• A failed search returns an empty row set rather than aborting, so an outage looks identical to "no stock in Overflow" — and produces a full-list shortfall email rather than an error.
• Bonded container cap unconfirmed — 15 CBM assumed.

TO-D9 · The unmerged branch appears to have been merged — this entry's deployment state is stale 🔴

Reading main for the script_updated date on 2026-08-21 returned HEAD 0ca95c7, dated 2026-08-17, whose message is "BE-3412: Transfer Order automation — allocation engine (create/amend, auto-approve, commit, shortfalls) (#3)". The Deployment state section above records BE-3412-APPLY-BUSINESS-LOGIC @ 47c0845 as unmerged and not deployed, and main @ 807826a as read-only step 1.

Only the dates and the commit subject were read — no code was re-verified — so this entry has not been changed to describe the merged state. Production wins over the entry: if the engine is now live, everything from Deployment state down needs re-verifying at 0ca95c7, and the production config's placeholder RESTlet ids (see above) become urgent rather than theoretical. Re-verify before relying on the deployment state recorded here.

The code and searches this reading was written from.

Do not edit these files — read-only per the access policy.

Deployed — main @ 807826a:

• transfer-order-automation-s10/index.mjs — handler, error/shortfall globals, run-end reporting
• transfer-order-automation-s10/controllers/app.mjs — orchestration (read → decide → write)
• transfer-order-automation-s10/controllers/netsuite.mjs — saved-search reads and RESTlet calls
• transfer-order-automation-s10/helpers/netsuite.mjs — token-based-auth client; account chosen entirely by the secret
• transfer-order-automation-s10/config/{production,staging}.mjs — search ids, script ids, recipients
• transfer-order-automation-s10/json/ — captured saved-search reference data and payload contracts

Not deployed — BE-3412-APPLY-BUSINESS-LOGIC @ 47c0845:

• transfer-order-automation-s10/controllers/businessLogic.mjs — the allocation engine
• transfer-order-automation-s10/controllers/createTO.mjs — write seam, create vs amend routing
• transfer-order-automation-s10/netsuite/createTransferOrder.js — create/amend script, approval guard, cap check
• transfer-order-automation-s10/controllers/aws.mjs — shortfall alert alongside the error email
• transfer-order-automation-s10/docs/allocation-engine-spec.md — the rules as written (see TO-D7)

The Asana task remains the source of truth for intent; where this entry and the task disagree, the task wins for intent and production wins for behaviour (CONVENTIONS.md §1).

What moved on this page, and when.

Inputs

Outputs