---
id: WF-COM-FUL-018
title: Check stock every night
trigger: 'The daily inventory schedule runs, or it is invoked on demand.'
product_area: commerce
module: fulfillment
revision: 1
status: draft
design_intent: confirmed
origin: >-
  Q08, Andrew 2026-10-19 (every page read):
  services-commerce:docs/migrations/inventory/README.md#D-P8I-24
implementation_evidence: observed
inference: []
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
implements:
  - CAP-COM-FUL-019
  - CAP-COM-FUL-018
moves:
  - STATE-COM-FUL-011
  - STATE-COM-FUL-009
crosses:
  - SVC-COM-FUL-inventory
idempotency: >-
  Standing findings accumulate occurrences. Released holds disappear from expiry
  candidates, and incomplete scans restart rather than retain a cursor.
concurrency: >-
  Reserved concurrency one prevents overlapping nightly functions. Other
  warehouse requests still run, and each diagnosis writes in its subject’s
  workspace.
hops:
  - 'n': 1
    actor_or_service: Nightly check
    action: Discover stock-bearing workspaces under the cross-workspace sweep policy.
    anchor: >-
      services-commerce:modules/inventory/services/persistence/inventory-items.ts:listTenantsWithInventoryAcrossTenants
    seam: schedule
    on_failure: Fail the run for later scheduled execution.
    left_inconsistent: No finding is written for unread workspaces.
    observer: Run logs.
    provenance: documented
    source: 'services-commerce:docs/migrations/inventory/README.md#D-P8I-08'
  - 'n': 2
    actor_or_service: Nightly check (per workspace)
    action: Release expired holds with their reason and retain expiry findings.
    anchor: >-
      services-commerce:modules/inventory/services/persistence/inventory-allocations.ts:expireHolds
    seam: sync
    on_failure: Log failed work for a later run.
    left_inconsistent: Expired holds can continue consuming availability.
    observer: Expired-hold findings.
    provenance: observed
    source: >-
      services-commerce:modules/inventory/services/reconciliation/nightly-inventory.ts:runNightlyInventory
  - 'n': 3
    actor_or_service: Nightly check
    action: >-
      Compare retained item balances with ledger derivation and report mismatch
      or negative-balance diagnoses.
    anchor: >-
      services-commerce:modules/inventory/services/persistence/inventory-items.ts:rederiveBalances
    seam: sync
    on_failure: Log read or finding failure.
    left_inconsistent: Disagreeing balances are not replaced.
    observer: Balance diagnoses.
    provenance: observed
    source: >-
      services-commerce:modules/inventory/services/reconciliation/nightly-inventory.ts
  - 'n': 4
    actor_or_service: Nightly check
    action: >-
      Detect terminal-obligation allocations and low-stock tracked SKUs with
      their reorder settings.
    anchor: >-
      services-commerce:modules/inventory/services/reconciliation/nightly-inventory.ts:runNightlyInventory
    seam: sync
    on_failure: Log the failed check.
    left_inconsistent: Undetected subjects remain without a new diagnosis.
    observer: Allocation and reorder findings.
    provenance: test
    source: >-
      services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory.integration.spec.js#raises
      stale_allocation on the committed unit whose obligation is cancelled
  - 'n': 5
    actor_or_service: Purchasing cost pass
    action: >-
      Compare physical stock with open cost layers and inspect recent outgoing
      movements for missing relief.
    anchor: >-
      services-commerce:modules/inventory/services/reconciliation/nightly-inventory.ts
    seam: sync
    on_failure: Log the failed cost check.
    left_inconsistent: Cost discrepancies remain for the owning process.
    observer: Cost diagnoses.
    provenance: observed
    source: >-
      services-commerce:modules/inventory/services/reconciliation/nightly-inventory.ts
  - 'n': 6
    actor_or_service: Nightly check
    action: >-
      Continue through pages while execution time permits, then report
      incomplete work with a margin.
    anchor: >-
      services-commerce:modules/inventory/services/reconciliation/nightly-inventory.ts
    seam: sync
    on_failure: >-
      Restart discovery on a later run rather than retaining a continuation
      cursor.
    left_inconsistent: The unexamined remainder waits for a sufficiently complete run.
    observer: Incomplete-run result and warning.
    provenance: documented
    source: 'services-commerce:docs/migrations/inventory/README.md#D-P8I-24'
branches: []
waits: []
evidence:
  - >-
    services-commerce at c8b66a98:
    modules/inventory/services/reconciliation/nightly-inventory.ts;
    aws/logic/inventory-nightly.lambda.ts;
    services/persistence/inventory-items.ts, inventory-allocations.ts,
    inventory-exceptions.ts.
controls: [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-LOG-004, 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]
---

# Check Stock Every Night

## What It Does

The nightly function discovers workspaces with stock, releases expired holds and compares item balances with ledger derivation. It also detects stale allocations, low stock and cost discrepancies. It follows pages while its execution budget allows.

## The Flow

```mermaid
sequenceDiagram
  participant C as Schedule 08:00 UTC
  participant N as Nightly check
  participant I as Items and ledgers
  participant F as Stock findings
  C->>N: run
  N->>I: workspaces with stock
  N->>I: release expired holds
  N->>I: re-derive balances
  N->>F: mismatches, stale, low stock, cost
  N-->>C: complete or incomplete
```

## When Something Fails

Checks retain findings rather than replacing disagreeing balances. A time-limited run reports incomplete work and restarts from the beginning next time. Stock findings remain separate from order Operations, so there is no shared console queue.