Reconcile shelf counts and stock findings

Purpose

Warehouse staff compare physical counts and ledger records and investigate discrepancies.

How It Works

Staff open a count for a warehouse or location and record observed quantities. Completion creates the necessary ledger corrections and retains the count record. Separate stock findings support acknowledgement and resolution of recurring problems. The nightly check compares balances, allocations, replenishment thresholds and cost evidence. It releases expired holds but leaves other discrepancies for investigation. Large scans can stop early and report incomplete coverage. The product should make incomplete runs and unresolved stock findings visible to the staff responsible for them.

Relationships

Keep stock movements and transfers accountable supplies or consumes related delivery records.
Allocate stock and explain what buyers can obtain supplies or consumes related delivery records.
Review and resolve operations findings supplies or consumes related delivery records.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Counts provide accountable shelf-balance corrections.Replenishment findings identify stock at its configured threshold.
Surfaces: apijob
Intent sources: services-commerce:docs/migrations/inventory/README.md#D-P8I-24 (Q08, Andrew 2026-10-19)

Controls

27 controls apply, from the corpus control catalogue.

TC-IAM-006 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-CRY-001 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-004 TC-LOG-005 TC-AVL-004 TC-MON-001 TC-MON-002 TC-MON-004 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`commerce.inventory.read`	api	tenant
`commerce.inventory.create`	api	tenant
`commerce.inventory.update`	api	tenant

Business Rules

12 rules, 11 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	A warehouse or location count starts without lines, records each item's on-hand expectation when counted, rejects items outside its scope and replaces a line's earlier count on recount. no proof recorded yet	lifecycle	service	test services-commerce:modules/inventory/tests/integration/services/stock/staff-movements.integration.spec.js#opens the count open with no lines, records the lines with what the shelf expected, and completes it with one correction for the variance
`02`must prove Proposed	Count completion writes keyed corrections for differences from on-hand at completion and stamps counted items, while rejecting later line edits and repeated completion; cancellation writes no corrections. no proof recorded yet	calculation	service	test services-commerce:modules/inventory/tests/integration/services/stock/staff-movements.integration.spec.js#refuses lines on a completed count and a second completion (409), and the cancelled count wrote nothing
`03`must prove Proposed	Each subject has one open stock finding per kind, repeats increase occurrences, resolution requires its result and cannot repeat, and later recurrence can open a new finding. no proof recorded yet	lifecycle	service, database	test services-commerce:modules/inventory/tests/integration/services/stock/staff-movements.integration.spec.js#is raised open, acknowledged, resolved with its resolution, and raised again as a new row once resolved
`04`must prove Proposed	The daily check releases expired holds with an expiry reason and raises an expired-hold finding for each, without automatically correcting other discrepancies. no proof recorded yet	lifecycle	service	test services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory.integration.spec.js#releases the expired hold (reason expiry) and raises expired_hold on it, giving the unit back
`05`must prove Proposed	Balance reconciliation compares stored balances with ledger derivation and reports both sets of figures without silently replacing them. no proof recorded yet	invariant	service	test services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory.integration.spec.js#raises balance_mismatch on the item knocked out of line, with what was kept and what the ledgers say, and corrects nothing
`06`must prove Proposed	A committed or picked allocation linked to a terminal delivery obligation produces a stale-allocation finding. no proof recorded yet	policy	service	test services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory.integration.spec.js#raises stale_allocation on the committed unit whose obligation is cancelled
`07`must prove Proposed	Tracked SKUs at or below their variant or fallback product reorder point produce low-stock findings carrying the applicable reorder quantity. no proof recorded yet	calculation	service	test services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory.integration.spec.js#raises low_stock on shirt L at its own reorder point with the product’s reorder quantity, and nothing on the cap above its point
`08`must prove Proposed	Inventory and tracked-product scans follow all pages when time permits, report incomplete work on early stopping and restart from the beginning on the next run. origin: Q08, Andrew 2026-10-19: services-commerce:docs/migrations/inventory/README.md#D-P8I-24 no proof recorded yet	policy	service	test services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory-paging.integration.spec.js#checks every tracked SKU with a reorder point and raises each one at or below it, the last page’s included
`09` Proposed	The cost reconciliation pass reports on-hand versus open-layer disagreement and recent outgoing shipment or transfer movements lacking relief.	policy	service	test services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory.integration.spec.js#raises valuation_mismatch on each item whose on-hand is not Σ its layers (the bare receipts made none), the cost stream’s finding
`10`must prove Proposed	Repeated nightly checks increment existing open findings rather than creating duplicates. no proof recorded yet	invariant	service	test services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory.integration.spec.js#finds the same on a second run and adds an occurrence to each open finding rather than another row
`11`must prove Proposed	Stock-workspace discovery requires sweep authority and rejects an existing transaction, while all resulting findings are stored within the relevant workspace. no proof recorded yet	invariant	service, database	test services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory.integration.spec.js#finds the tenants that hold stock across tenants, under the sweep policy, this one among them, and refuses that read inside another transaction
`12`must prove Proposed	Count creation, recording and completion and finding acknowledgement or resolution require administrator inventory permissions. no proof recorded yet	permission	api	observed services-commerce:modules/inventory/aws/api/inventory.routes.ts

Scenarios

Id	Given	When	Then	Provenance
`01`	The shelf contains nine units but on-hand records show ten.	Record and complete the shelf count.	One negative count correction aligns the balance and stamps the count time.	test services-commerce:modules/inventory/tests/e2e/inventory.e2e.spec.js#opens a count, records what was counted, completes it with one correction, and cancels another; lines on a completed count 409

Edge Cases

Id	Given	When	Then	Provenance
`02`	Tracked merchandise spans several pages.	Run the full nightly scan.	Low-stock evaluation reaches qualifying SKUs on the final page as well.	test services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory-paging.integration.spec.js#checks every tracked SKU with a reorder point and raises each one at or below it, the last page’s included

Planning

Reconcile shelf counts and stock findings ​

Purpose ​

How It Works ​

Relationships ​