0047: Inventory on the block, purchase orders stay hand-built

Stock, locations, allocations, counts and movements move to the inventory block in one breaking cutover. Purchase orders stay hand-built and receive into the block with move_stock.

Status: Accepted
Date: 2026-11-06

Context

ADR 0046 installed the inventory block next to the hand-built stock tables. The hand-built model keeps one stock record per product, location, lot and serial, an allocation table with one owner column per document type, and a movement table. The block keeps stock levels per variant and location, buckets per bin and lot, serial numbers, allocations keyed by document type and id, stock counts, transfers and a ledger of movements.

The block also has purchase orders and receipts. They have no numbering, no lifecycle, no tax lines and no canceled quantity. CentraKit purchase orders have an organization number sequence, a lifecycle workflow, a PDF, a send step, an exchange rate and a supplier that is a customer with the supplier role.

Decision

Stock levels, bins, lots, serials, locations, allocations, reorder points, counts, transfers and movements move to the inventory block in one breaking cutover. The old tables and functions are dropped, with no compatibility layer.
Allocations are stock_allocations rows keyed by document type (task_material, quote_version_line, invoice_line, order_line) and document id. Reserved, backordered and consumed map to allocated, backordered and fulfilled. Consuming calls take_allocation, and returning calls restore_allocation.
Existing stock migrates as one posted stock count per location.
Purchase orders stay hand-built. Receiving a purchase order calls move_stock with the reason receipt, and the purchase order lines keep the received quantity. The incoming column of the stock levels follows open purchase order lines.
The tables that referenced public.inventory_locations with a composite (id, organization_id) key (customers, templates, purchase orders, shipments and reorder rules) reference the block's location with the same composite key. The block table has no such unique key, so CentraKit adds a unique index on (id, organization_id) to better_supabase.inventory_locations in supabase/schemas/catalog/inventory_stock.sql.
The functions the block lacks are written by hand in CentraKit: moving an allocation between owners, releasing part of an allocation, and a movement list read.

Gaps to report to better-supabase

Purchase orders need numbering, a lifecycle, tax lines and a canceled quantity before CentraKit can adopt them.
Allocations need a transfer between documents and a partial release.
The inventory block needs a movement list read with the document reference and the bin and lot, and read functions in the api schema for stock levels and locations.
inventory_locations needs a unique (id, organization_id) key so other tables can use composite foreign keys.
stock_levels.incoming is not maintained by the block. CentraKit computes incoming quantity from open purchase order lines in inventory_variant_incoming.
Serial-tracked variants need the serial numbers on every outgoing movement. CentraKit picks them in stock_serial_detail; the block could offer a pick helper.

Known approximations

The cost snapshot of an invoice line uses the weighted average cost of the stock item at the time of sending, not the cost of the units that were allocated.
Invoice returns of serial-tracked variants restock the quantity but not the original serial numbers.
The demo seeds write the old record-per-location shape into scratch tables, and 169_inventory_block.sql posts it as one count per location. Movement history of the demo data starts at that count.

Consequences

Services, API routes, MCP tools and the UI read stock levels per location and bin instead of stock records.
Imports can post stock as a count, so a newer backup posts only the difference.
Moving to block purchase orders later replaces the hand-built receive step with the block receipt functions.

Last updated on

0047: Inventory on the block, purchase orders stay hand-built

Stock, locations, allocations, counts and movements move to the inventory block in one breaking cutover. Purchase orders stay hand-built and receive into the block with move_stock.

Status: Accepted
Date: 2026-11-06

Context

Decision

Stock levels, bins, lots, serials, locations, allocations, reorder points, counts, transfers and movements move to the inventory block in one breaking cutover. The old tables and functions are dropped, with no compatibility layer.
Allocations are stock_allocations rows keyed by document type (task_material, quote_version_line, invoice_line, order_line) and document id. Reserved, backordered and consumed map to allocated, backordered and fulfilled. Consuming calls take_allocation, and returning calls restore_allocation.
Existing stock migrates as one posted stock count per location.
Purchase orders stay hand-built. Receiving a purchase order calls move_stock with the reason receipt, and the purchase order lines keep the received quantity. The incoming column of the stock levels follows open purchase order lines.
The tables that referenced public.inventory_locations with a composite (id, organization_id) key (customers, templates, purchase orders, shipments and reorder rules) reference the block's location with the same composite key. The block table has no such unique key, so CentraKit adds a unique index on (id, organization_id) to better_supabase.inventory_locations in supabase/schemas/catalog/inventory_stock.sql.
The functions the block lacks are written by hand in CentraKit: moving an allocation between owners, releasing part of an allocation, and a movement list read.

Gaps to report to better-supabase

Purchase orders need numbering, a lifecycle, tax lines and a canceled quantity before CentraKit can adopt them.
Allocations need a transfer between documents and a partial release.
The inventory block needs a movement list read with the document reference and the bin and lot, and read functions in the api schema for stock levels and locations.
inventory_locations needs a unique (id, organization_id) key so other tables can use composite foreign keys.
stock_levels.incoming is not maintained by the block. CentraKit computes incoming quantity from open purchase order lines in inventory_variant_incoming.
Serial-tracked variants need the serial numbers on every outgoing movement. CentraKit picks them in stock_serial_detail; the block could offer a pick helper.

Known approximations

The cost snapshot of an invoice line uses the weighted average cost of the stock item at the time of sending, not the cost of the units that were allocated.
Invoice returns of serial-tracked variants restock the quantity but not the original serial numbers.
The demo seeds write the old record-per-location shape into scratch tables, and 169_inventory_block.sql posts it as one count per location. Movement history of the demo data starts at that count.

Consequences

Services, API routes, MCP tools and the UI read stock levels per location and bin instead of stock records.
Imports can post stock as a count, so a newer backup posts only the difference.
Moving to block purchase orders later replaces the hand-built receive step with the block receipt functions.

Last updated on

0047: Inventory on the block, purchase orders stay hand-built

Context

Decision

Gaps to report to better-supabase

Known approximations

Consequences

On this page

0047: Inventory on the block, purchase orders stay hand-built

Context

Decision

Gaps to report to better-supabase

Known approximations

Consequences

On this page

0047: Inventory on the block, purchase orders stay hand-built

ContextCopy Anchor Link

DecisionCopy Anchor Link

Gaps to report to better-supabaseCopy Anchor Link

Known approximationsCopy Anchor Link

ConsequencesCopy Anchor Link

On this page

0047: Inventory on the block, purchase orders stay hand-built

ContextCopy Anchor Link

DecisionCopy Anchor Link

Gaps to report to better-supabaseCopy Anchor Link

Known approximationsCopy Anchor Link

ConsequencesCopy Anchor Link

On this page

Context

Decision

Gaps to report to better-supabase

Known approximations

Consequences

Context

Decision

Gaps to report to better-supabase

Known approximations

Consequences