Warehouse stock reconciliation CLI from CSV files

Build a dependency-free Node.js 24 warehouse stock reconciliation CLI from two CSV inputs. No web server or browser UI. Entry point: node stock-reconcile.js --opening <path> --events <path> --out <directory>. --help documents usage and exits 0. Successful reconciliation exits 0 and writes stock.csv and audit.json into the output directory. Errors exit nonzero, identify input/row on stderr, and preserve existing outputs and inputs byte-for-byte; wording is otherwise unspecified. Refuse output destinations that would overwrite either input. Validate the entire dataset before publishing outputs. No network calls or npm runtime dependencies. CSV: UTF-8 with optional BOM, LF/CRLF, quoted commas, doubled quotes and embedded newlines. Require exact headers below; reject malformed quoting, missing/extra columns and blank IDs. Final newline allowed; internal blank records refused. IDs are case-sensitive; do not trim. Quantities must consist of decimal digits and be safe integers; opening onHand may be zero, event quantities must be positive. Reject arithmetic beyond Number.MAX_SAFE_INTEGER rather than silently rounding. opening.csv header: sku,onHand. Each SKU occurs exactly once. Initial reserved quantity is zero. events.csv header: id,sku,type,quantity,ref. Apply rows in file order. All SKUs must exist in opening.csv. Supported types: - RECEIVE: ref must be empty; add quantity to onHand. - RESERVE: ref is a new, nonempty reservation ID, globally unique within this reconciliation; reserve quantity only when onHand minus reserved is sufficient. onHand is unchanged. - RELEASE: ref names an existing reservation on the same SKU; release up to its remaining reserved quantity. onHand is unchanged. A fully released reservation cannot be reused under the same ID. - SHIP: ref names an existing reservation on the same SKU; ship up to its remaining quantity, subtracting the quantity from onHand and reserved. - RETURN: ref names an earlier SHIP event ID on the same SKU; add quantity back to onHand, without recreating a reservation. Cumulative returns for a shipment cannot exceed that shipment's quantity. All quantities and balances must stay nonnegative. Unknown references, cross-SKU references, over-release, over-shipment and over-return are errors. Event IDs are global: repeating an identical parsed row with the same ID is an idempotent duplicate and has no effect; the same ID with different fields is an error. Check duplicates before transitions; a repeated shipment after reservation exhaustion stays harmless. stock.csv has header sku,onHand,reserved,available and rows sorted by SKU using JavaScript string comparison, with correct CSV escaping and LF line endings. Include zero-stock SKUs. audit.json is deterministic, without timestamps/temporary paths; record each event row's ID, applied/duplicate disposition and before/after onHand,reserved,available for its SKU. Also expose counts of applied and duplicate rows. An opening-only reconciliation is valid. Provide npm test using node:test, with subprocess tests that execute the CLI on isolated temporary directories. Cover successful partial reservation/release/shipment/return sequences, repeated shipment IDs, conflicting duplicates, invalid prerequisites, overflow, quoted multiline identifiers, CRLF/BOM inputs, deterministic repeat execution and preservation of pre-existing outputs on a late invalid row. Assert setup and resulting state, not only exit status. Provide examples and a README with usage, formats and rules. As a fixed acceptance example: opening A=10 and B=0; RESERVE 6 of A under R1, SHIP 4 under R1 with event ID S1, repeat exactly S1, RELEASE 2 under R1, RETURN 3 referencing S1, RECEIVE 7 of B, RESERVE 2 of B under R2. Final A is onHand=9,reserved=0,available=9; B is onHand=7,reserved=2,available=5; applied rows=6 and duplicate rows=1. A further RETURN 2 referencing S1 must fail and preserve existing outputs. Report executed evidence, actual corrections and gaps accurately.

Finish the seeded warehouse CLI and its proofs; retain all five prior repairs. Reproduce and fix three independently observed bugs: CRLF header + valid RECEIVE + invalid zero-quantity row reports row 1 instead of row 3; an output directory symlink to the input directory lets output stock.csv overwrite opening input stock.csv; existing stock.csv is replaced before publishing audit.json fails when audit.json is a nonempty directory. Refuse unsafe destinations and preserve pre-existing bytes on publication failure. Fill the prior test gaps: with valid prerequisites, prepopulate outputs before conflicting duplicate and excess-return failures and compare BOTH outputs and inputs before/after; check the actual refusal cause. Assert opening-only/zero-stock content, identical SHIP duplication after reservation exhaustion, true extra-column rows, arithmetic overflow distinct from unsafe input integers, and direct input/output collision. Do not replace assertions with names or success prose. Report remaining gaps accurately. Full retained contract: CSV is UTF-8 with optional BOM, LF/CRLF, quoted commas, doubled quotes and embedded newlines. Headers are exactly opening: sku,onHand and events: id,sku,type,quantity,ref. Reject malformed quoting, missing/extra columns, blank IDs and internal blank records; allow final newline. IDs are case-sensitive, not trimmed. Opening SKUs are unique. Quantities contain decimal digits and are safe integers: opening onHand >=0, event quantity >0. Reject arithmetic overflow; all balances stay nonnegative. Events run in file order, on existing SKUs. RECEIVE has empty ref and adds onHand. RESERVE uses a new nonempty reservation ID globally unique for the entire reconciliation, reserves only available stock and leaves onHand unchanged. RELEASE references a same-SKU reservation, releases up to remaining quantity, leaves onHand unchanged; never reuse its ID after exhaustion. SHIP references a same-SKU reservation, subtracts up to remaining quantity from onHand and reserved. RETURN references an earlier same-SKU SHIP event ID, restores onHand only, and cumulative returns cannot exceed that shipment. Unknown/cross-SKU references, over-release, over-shipment and over-return fail. Event IDs are global: identical parsed repeated rows are harmless duplicates, checked BEFORE transitions, including a repeated shipment after exhaustion. Same event ID with different fields fails. Validate the whole dataset before publishing. Any error exits nonzero, identifies input/row on stderr and preserves inputs and existing stock.csv/audit.json byte-for-byte, including late invalid rows. Refuse output destinations overwriting either input. Successful runs exit 0. stock.csv header sku,onHand,reserved,available; sort SKUs by JavaScript string comparison, escape CSV, use LF and include zero-stock SKUs. audit.json has deterministic per-row ID, applied/duplicate disposition and before/after onHand,reserved,available plus counts, without timestamps or temporary paths. Opening-only input works. Fixed example: opening A=10,B=0; RESERVE A6 R1; SHIP A4 R1 with ID S1; repeat S1 exactly; RELEASE A2 R1; RETURN A3 S1; RECEIVE B7; RESERVE B2 R2. Final A=9/0/9,B=7/2/5; applied=6,duplicates=1. Further RETURN A2 S1 fails preserving existing outputs. npm test uses node:test and actual CLI subprocesses in isolated directories. Assert setup, resulting state and relevant errors, not exit status alone. Explicitly execute conflicting duplicate fields with valid prerequisites and compare existing outputs before/after. Run valid inputs twice and compare BOTH stock.csv AND audit.json byte-for-byte. Check opening-only and zero-stock output content. Cover partial transitions, all invalid prerequisites, safe arithmetic, quoted multiline/last-column CSV, BOM/CRLF, input preservation and late failure. Report actual executed evidence and remaining gaps accurately.

Fix the overbroad output-directory refusal in the seeded warehouse CLI without changing its existing reconciliation contract or removing any passing regression assertions. The current implementation refuses outIdentity equal to an input parent directory. That is too broad: only destinations that would overwrite an actual input identity should be refused. Concrete VALID cases: in one directory, opening.csv contains sku,onHand then A,10; events.csv contains its normal header then e,A,RECEIVE,1, . With --out . the CLI must exit 0, preserve both inputs byte-for-byte, and write stock.csv containing A,11,0,11 and a matching audit with one applied event. A directory symlink alias pointing to that same directory must also succeed when used as --out alias. Outputs have different names from both inputs, so neither case is a collision. Concrete INVALID cases: when the opening input itself is named stock.csv in the destination directory, --out pointing directly there OR to its directory symlink must refuse before changing any input/output bytes. Preserve direct events-input collisions, the audit.json-directory publication failure protection, rollback, CRLF row diagnostics, all reservation/CSV/quantity fixes, deterministic outputs and duplicate/excess-return preservation. Correct the existing symlink regression fixture: it currently calls a non-colliding directory unsafe and encodes the undesired restriction. Replace that assertion with the two valid cases AND real direct/symlink input collisions. This changes an incorrect test convention, not the safety requirement. Assert exit status, actual output/audit state, input byte preservation and the right refusal cause. Run the full existing subprocess suite and document accurately what passed. Keep the change narrowly scoped and retain the seven existing acceptance criteria.