The stock ledger

The platform's stock is kept in a signed ledger: Product.stockLedger is the authority (it may go negative — a real backorder), and Product.stock is only its clamped display mirror (stock == max(0, stockLedger)). This page is the reference for the model: why it exists, the anatomy of a StockAction, the trustedStock trust boundary that supplier ordering reads through, and the invariants that keep it all honest.

For the end-to-end flow (stock → reordering → vendor email), see the overview; for every individual write site, see write paths.

The Option B model (#2886)

Two columns on Product, one contract:

Every physical movement records the true signed delta in the ledger, even when it drives it below zero. The next receipt nets the backorder instead of stacking free stock on top of a counter clamped at 0. The math is a pure function shared by every write site:

packages/services/src/stock/rolling-stock-math.ts   → computeStockWrite / displayStock
packages/services/src/stock/stock-ledger.service.ts → recordPhysicalMovement

The signed behaviour is gated by STOCK_LEDGER_ALLOW_BACKORDER (true in production since 2026-07-09T20:00Z). With the flag off, the math falls back byte-for-byte to the old clamped model — the fix only exists under the flag.

Why a signed ledger — three generations of the same bug

The current model answers a well-documented incident class:

1. May 2026 — the original phantom stock. Virtual PENDING StockAction rows were created for manageStock=false products, with quantityBefore=0 stubbed in; supplier-order regenerations cancelled the source without reversing the COMPLETED increments already applied. Result: ~912 phantom units across ~57 products, and under-ordered supplier orders (Bio Rennes 2026-05-06: 6 lines where 39+ were needed).
2. #2728 — multi-source drift. Product.stock, the quantity synced from PrestaShop and Σ(stockAction) silently disagreed: three incompatible "truths", none reliable.
3. #2886 — the clamp under just-in-time flow. In a rolling operation with no safety stock, physical stock legitimately sits at 0 between receipts. A client delivery sealed at stock 0 was clamped (max(0, 0 − qty) = 0): the consumption was silently lost, the next receipt created phantom stock, and the following supplier order was undersized (measured case: Baron 31 → 26). The trap: this phantom passed the audit, because stock == stockLedger == the fictional value — internally consistent, physically wrong.

The signed ledger makes clamp-born phantoms structurally impossible: the −5 of a delivery at stock 2 is recorded in full (ledger −3), and the receipt of 10 lands on 7, not 10.

Anatomy of a StockAction

Every movement — real or projected — is a StockAction row (packages/db/prisma/schema/order.prisma):

Only COMPLETED rows count toward the ledger: stockLedger caches Σ quantityChange over the product's COMPLETED SAs. PENDING rows are projections — reserved-in ("virtual entry" from an issued supplier order) and reserved-out ("virtual exit" from a client order) — and touch neither stock nor stockLedger.

Lifecycle and reversal rules

stateDiagram-v2
    [*] --> PENDING : projection created (supplier order issued, client order)
    PENDING --> COMPLETED : confirmed at the physical movement
    PENDING --> CANCELLED : source cancelled or regenerated (no stock effect)
    COMPLETED --> [*] : deletion = reverseCompleted (ledger -= quantityChange)
    CANCELLED --> [*]
    note right of COMPLETED
        The only state that writes the ledger.
        quantityBefore/After recomputed
        against the real ledger on confirm.
    end note

The rules, in the order they were learned:

• PENDING → COMPLETED (confirmStockAction / StockLedgerService.transitionToCompleted): quantities are recomputed against the current ledger at confirm time — the projection's stubbed values are never trusted. Under Option B the base is stockLedger and Product.stock receives the clamped mirror.
• PENDING → CANCELLED: no stock effect. This is the normal fate of a projection whose source is cancelled or regenerated.
• COMPLETED is never silently cancelled. Deleting a movement goes through reverseCompleted (in stock-actions.service.ts): the ledger is decremented by the exact quantityChange, then Product.stock is rewritten as the clamped mirror of the reversed ledger. Reversing "by applied delta" is wrong for movements that crossed zero — which is precisely the historical bug.
• Never stub quantityBefore=0. Read the real ledger first (May 2026 incident).
• The PROCESSING, FAILED, PARTIAL, VALIDATED, REJECTED statuses exist in the enum, but the three states above carry all of the ledger semantics.

manageStock semantics

manageStock separates tracked products from untracked ones:

The trust boundary: trustedStock

All supplier-order math reads stock through one function, trustedStock() (packages/services-supplier-order/src/utils/supplier-order-utils-new.ts). It decides how many on-hand units are credible when sizing a supplier order:

flowchart TD
    A[Product] --> B{STOCK_LEDGER_PESSIMISTIC ?}
    B -->|true| Z0["return 0 (kill switch)"]
    B -->|false| C{manageStock ?}
    C -->|false| Z0
    C -->|true| D{"made-to-order vendor<br/>AND count not merchant-validated ?"}
    D -->|yes| Z0
    D -->|no| E{vendor.useStockLedger ?}
    E -->|yes| F{STOCK_TRUST_ALLOW_NEGATIVE ?}
    F -->|yes| G["raw = stockLedger (signed)"]
    F -->|no| H["raw = max(0, stockLedger)"]
    E -->|no| I["raw = max(0, stock)"]
    G --> J{"data.stockTrusted<br/>(validated count) ?"}
    H --> J
    I --> J
    J -->|yes| K[return raw]
    J -->|no| L["ceiling = weekly consumption × STOCK_TRUST_MAX_COVER_WEEKS<br/>return min(raw, ceiling)"]

The guards, one by one:

• STOCK_LEDGER_PESSIMISTIC — the kill switch (#2728). true ⇒ stock is ignored everywhere (returns 0, over-ordering accepted, drafts are reviewed before sending). OFF in production: the ledger has been trusted since every write site became audited.
• manageStock=false ⇒ 0 — an untracked product provides no coverage.
• Made-to-order (madeToOrder) ⇒ 0 — a vendor holding no inventory has no real shelf stock; its "on hand" is a validation artefact. Exception #2932: if the merchant has explicitly validated a count (data.stockTrusted), the value counts.
• Negative ⇒ clamped to 0 (#2725) — unless the STOCK_TRUST_ALLOW_NEGATIVE gate is on (OFF in prod): once enabled, a negative ledger passes through as-is and the backorder grows the next order. The flip is planned after ≥ 4 weeks of a green I6 invariant. The legacy Product.stock path always stays clamped.
• The anti-phantom ceiling — STOCK_TRUST_MAX_COVER_WEEKS (8 in prod): never trust more than N weeks of recent consumption (Σ of COMPLETED DECREMENTs over the last 8 weeks, attached by attachRecentWeeklyConsumption). A product showing 991 on hand but ~1 sale/week is almost certainly inflated PrestaShop stock — the ceiling caps it. Zero consumption ⇒ ceiling 0 ⇒ stock fully distrusted: order the full demand, the conservative direction (over-order, never stock out).

Invariants I1–I7

The stock-ledger-audit task (packages/scripts/src/tasks/stock-ledger-audit.ts) continuously verifies the ledger:

# Report (read-only)
cd apps/app && bun run cli --task stock-ledger-audit --tenantId <uuid> --siteId <uuid>

# CI gate / probe — throws on any violation
cd apps/app && bun run cli --task stock-ledger-audit --tenantId <uuid> --siteId <uuid> --strict

# Heal (cancel orphans, resync mirrors, …)
cd apps/app && bun run cli --task stock-ledger-audit --tenantId <uuid> --siteId <uuid> --apply

Under Option B, the I5 heal resyncs only the display mirror — the Σ of COMPLETED SAs is the authority; a backfill SA is never written to make the counter match.

Worked example: a backorder, step by step

The canonical just-in-time scenario — a client delivery goes out before the covering receipt is recorded. Watch both columns.

quantityBefore = 2        (real ledger, never a stub)
quantityChange = −5       (the TRUE delta — no clamp)
quantityAfter  = −3       (signed ledger)
Product.stock  = max(0, −3) = 0

quantityBefore = −3
quantityChange = +10
quantityAfter  = 7
Product.stock  = max(0, 7) = 7

Production flags

State verified on the production tenant (see Configuration for the full matrix):

See also

• Stock & reordering overview — the full flow on one page
• Write paths — every site that writes the ledger
• Supplier orders — the event-driven reordering that reads trustedStock
• The daily timeline — the 06:00 / 06:30 / 07:15 / 12:01 crons
• PrestaShop sync — ledger-integrated sync writes (#2749)
• Safety nets — audit, replay diff, pinned tests, health probe
• Back office — ledger timeline, manual movements, StockAction journal
• Configuration — the full flag matrix