G3N Retail Stack Story

Appearance

Inventory Control (ICS) ​

Status: Implemented (core + transfer analytics; baseline replenishment suggestions + average-cost tracking).

Purpose ​

ICS owns the real-time inventory truth, bin-level warehouse operations, and the immutable stock card history for each variant at each logical facility.

Goals ​

  • Provide accurate, near-instant stock availability for operational decisions.
  • SKU-only stock lookups return a list across authorized logical facilities (responses include logical_guid).
  • Support WMS-grade receiving, putaway, picking, packing, shipping, and transfers.
  • Preserve immutable stock card history with full auditability and context.
  • Support ownership vs possession and virtual/external locations.
  • Provide fast current and historical views (at least 24 months) plus projections.
  • Projections are based on inbound pipelines and transfers and may be slower than operational queries.

Non-goals ​

  • ICS does not define sellability (owned by PMC).
  • ICS does not define product truth (owned by PVM).
  • ICS does not define final pricing (owned by PPM).

Scope and gating ​

  • All inventory is org-scoped.
  • Operational actions are logical-facility scoped.
  • Channel context is required when stock is reserved, allocated, or committed for a channel.
  • Org-wide inventory views are analytics rollups, not operational truth.

Request context checklist ​

  • Org: required for all inventory operations.
  • Logical facility: required for operational actions.
  • Channel: required when reserving, allocating, or committing stock to a channel.
  • Actor + role: required for approvals and adjustments.
  • Cost-centre: optional attribution for billing and audit.

Core business entities and relationships ​

  • Stock position: variant + logical facility + bin/zone location.
  • Location hierarchy: facility -> zone -> bin, plus staging, receiving, shipping, and quarantine.
  • Stock card event: immutable record of a stock, cost, or state change with reason, actor, comments, and source references.
  • Stock card entries reference source records (PO lines, invoice lines, receipt lines, transfers, counts, adjustments, returns).
  • Ownership vs possession: own+possess, own-not-possess, possess-not-own, in-transit.
  • Virtual/external locations: 3PL, partner, vendor, or in-transit nodes with controlled transitions.

Ownership vs possession examples (concrete)

Consignment sale

  • Facility F1 holds 10 units on consignment: possess-not-own (owner = Vendor V, possessor = Org O at F1).
  • A sale ships 2 units: ICS reduces possessed quantity; owned quantity for Org O is unchanged.
  • ICS emits a consignment consumption event referencing the sale; settlement later records financial transfer from Org O to Vendor V.
  • A return reverses the consumption event and restores possessed quantity; ownership still remains with Vendor V.

Inter-facility transfer

  • Facility F1 has 20 units own+possess (owner = Org O, possessor = Org O at F1).
  • A transfer request ships 5 units to Facility F2:
    • At shipment: F1 possession decreases by 5; stock enters in-transit (owner = Org O, possessor = in-transit node).
    • At receipt: F2 possession increases by 5 and becomes own+possess at F2.
  • Stock card events at each step carry reason codes and source references to the transfer request/shipment/receipt.

Lifecycle and status model (described in words) ​

  • Inventory enters via receiving into a receiving or quarantine location.
  • Quarantine stock transitions to available only after QC or approval.
  • Explicit stock reclassification uses stock/transition to move quantities between available, quarantine, and damaged buckets with reason codes.
  • Available stock can be reserved, allocated, and committed for fulfillment.
  • In-transit stock exists only during transfers or returns and must reconcile to a destination location.
  • Damaged or shrink states require reason codes, approvals (when configured), and audit trails.
  • Consignment-held stock tracks possession separately from ownership and follows its own settlement rules.

End-to-end workflows ​

Inventory promise contract (SCM ↔ ICS) ​

  • Lifecycle: reserve → allocate → commit → release.
  • Reserve TTL defaults (policy baseline, channel/facility overrides allowed):
    • POS 5 minutes, ecommerce 15 minutes, wholesale 60 minutes.
  • Allocate TTL default: 120 minutes (or end of pick wave, whichever is sooner).
  • Commit TTL default: ship-from-store 24 hours; pickup orders align to the pickup window.
  • Allocation/commit holds may include expires_at timestamps from SCM; ICS records and emits the expiry for reconciliation.
  • Release reason codes (baseline): payment_failed, approval_failed, customer_cancelled, inventory_expired, pickup_no_show, substitution_declined, fraud_hold.
  • Short-ship reasons (baseline): insufficient_available, damaged, qc_hold, recall_hold, lost_in_pick, carrier_constraint.
  • Partial-commit policy: default allow partial for B2C channels; wholesale defaults to hard-fail unless backorder policy allows split.

Happy paths ​

  • Receive -> QC (optional) -> directed putaway -> available -> pick/pack/ship.
  • Replenish from overstock to pick-face based on min/max rules.
  • Transfer between facilities with in-transit visibility and confirmation at destination.
  • Cycle count adjustments recorded on the stock card and reconciled with tolerance rules.

Exceptions and edge cases ​

  • Partial receipts, over/under shipments, wrong item, or damaged goods.
  • Misrouted or lost-in-transit transfers with reconciliation adjustments.
  • Short picks, substitutions, or shipment discrepancies with reason codes.
  • Cross-facility returns received at a different logical facility.
  • Return dispositions recorded (restock, quarantine, refurb, scrap) with reason codes.
  • Manual adjustments with actor, comment, and source reference captured.
  • Physical and cycle count adjustments recorded as distinct stock card events.

Configuration and defaults ​

  • The platform is enterprise-grade by default; applications may hide complexity via defaults.
  • Negative stock protection is configurable per logical facility + variant; when disabled, reservations/commits may overcommit and backorder policies can respond accordingly.
  • Overcommit emits stock-overcommitted events for backorder queueing and recovery workflows.
  • Configurable pick methods: discrete, batch, wave, and zone picking.
  • Replenishment: pick-face vs overstock, min/max, forward-pick replenishment.
  • Replenishment rules capture pick-face bin, overstock bin, min/max thresholds, and status per logical facility.
  • Replenishment execution is recorded as a bin-to-bin movement with a stock card entry.
  • Cycle counting: ABC classification, count frequency rules, tolerance thresholds, and recount workflows.
  • Traceability: optional lot/serial tracking, expiry control, FIFO/FEFO implemented (multi-lot FEFO splitting via selectLotPositions).
  • Loss controls: reason codes, approvals, and audit trails.
  • Receiving: partials, over/under, QC/quarantine, and damage workflows.

Transfer and allocation planning (best-practice expectations) ​

  • Separate recommendations from execution: candidate transfers and allocations are suggestions with analytics; actual transfer requests require explicit approval.
  • Transfer requests follow draft -> pending approval -> submitted when approval is required; thresholds are % and $ values set per org with optional facility overrides. Approvals capture approver, timestamp, and reason, with optional no-self-approval rules for high-risk transfers.
  • Current implementation (MVP): suggestions are rule-based using min/max replenishment rules plus current availability; advanced factors below are policy expectations to layer in.
  • Suggestions include rationale, expected impact, constraints triggered, and recommended quantities/timing.
  • Configurable factors (org-level with optional facility overrides):
    • Sales velocity by channel and facility.
    • Forecasted demand and planned promotions or price changes.
    • Transfer lead times, carrier windows, and transfer cost per unit.
    • Hard gates for min/max on-hand, min/max send quantities, and safety stock.
    • Presentation minimums and assortment compliance requirements.
    • Open orders, reservations, and backorders.
    • Inbound supply and in-transit inventory.
    • Shelf life, expiry, lot/serial constraints, FEFO rules, and local markdown timing.
    • Margin, markdown risk, and profitability thresholds.
    • Space utilization limits (staging constraints, backroom capacity).
    • Pick/pack friction (labor complexity, special handling, bulky items).
    • Storage capacity, labor capacity, and handling constraints.
    • Channel priority and service-level targets.
    • Customer experience risk (late delivery penalties, marketplace SLAs).
    • Substitution tolerance by category.
    • Cross-channel cannibalization impacts on availability.
    • Ownership/consignment constraints and transfer eligibility.
    • Regional compliance (regulated goods by location) and temperature/handling constraints.

Transfer execution and shipment handling ​

  • A transfer request may be fulfilled as one or more shipments.
  • Each shipment has its own status and exception handling (partial ship, loss, damage, misroute).
  • Receiving supports partial receipts and reconciliation against expected quantities.
  • Transfers move to receiving until all shipments are received; final status is received or received_with_exceptions based on recorded short/damage exceptions.

Reorder management and analytics ​

  • Transfer analytics -> reorder insights: persistent transfer-out indicates reorder points too low at a facility or too high at the source; lead-time variance informs safety stock; transfer cost vs vendor cost signals when rebalance is cheaper than new procurement; short-ship/failure reasons show where buffers or alternate sources are needed; transfer patterns reveal regional demand shifts and cross-channel cannibalization.
  • ICS provides transfer report summaries (status counts, open-transfer counts, lead-time averages, shipment/exception totals) with optional source/destination and source→destination pair breakdowns for operational review and reorder planning.
  • Transfer reports can optionally bucket counts by time (requested/shipped/received per day/week/month) and include lead-time buckets for faster variance analysis.
  • Recommendations: segment by velocity/variability (ABC/XYZ) with continuous vs periodic review; use reorder point + order-up-to with MOQs, case packs, capacity, shelf-life, and regulatory constraints; make safety stock dynamic using service-level targets, lead-time variability, promo calendars, and planned price changes; support multi-echelon logic (transfer-first vs vendor buy); use exception-first workflows with reasons/approvals; preserve temporal truth with "as-of" inventory, price, and cost context for audit and post-mortem.

Cost and valuation requirements ​

  • Current implementation (MVP): optional unit_cost on receipts, adjustments, and transfers; weighted-average cost per logical facility; cost_delta recorded on stock card entries. unit_cost.currency must match the existing average cost currency. FX conversion, landed-cost allocation, and multi-model valuation are not implemented yet.
  • Aspirational (not yet implemented): track average cost at the logical facility level, including full landed cost inputs (freight, tariffs/duties, brokerage, handling, insurance).
  • Aspirational: support multiple average-cost models in parallel: a default per org plus optional analytics models (true vs windowed vs projected).
  • Aspirational: windowed analytics can ignore older data without altering the true average cost.
  • Aspirational: support FX impacts; preserve original and converted amounts for audit and reconciliation.
  • Aspirational: support projected restocking impacts without mutating actual average cost.
  • Aspirational: allow optional dwell-time cost adjustments based on time held at a facility.
  • Aspirational: capture transfer-related cost adjustments between logical facilities.
  • Aspirational: receiving facilities calculate average cost using a defined transfer cost basis (source cost plus transfer-related adjustments), with org policy and optional facility overrides.

Omnichannel requirements ​

  • Support BOPIS, curbside, ship-from-store, ship-to-home, and delivery operations.
  • Support split fulfillment across facilities with clear traceability.

Performance requirements ​

  • Stock availability checks, reservations, and movement updates must be near-instant.
  • Receiving, putaway, and scan-based workflows must support high throughput.
  • Transfers and returns processing must be near-instant.
  • Pick, pack, and ship workflows must be near-instant.
  • Historical inventory views must be fast for at least 24 months; projections can be slower.
  • Grouped inventory views (by category, department, or dynamic facets) must be fast.
  • Approval checks must not slow operational inventory actions.

Operational resilience checklist ​

  • Operations are idempotent and retry-safe; duplicate submissions do not double-apply.
  • Event emission is non-blocking; operational actions do not wait on analytics pipelines.
  • Out-of-order events are tolerated; reconciliation uses timestamps and source references.
  • Exceptions generate actionable inbox items and can be retried or reversed with audit trails.
  • Long-running workflows are resumable with explicit state checkpoints.

Training and change management ​

  • Policy and workflow changes include training notes and operational checklists.
  • Critical changes use staged rollout with rollback guidance to reduce operational risk.
  • Support runbooks cover common exceptions, disputes, and stock reconciliation steps.

BI and KPI expectations ​

  • Inventory accuracy, shrink rate, and count variance by facility and category.
  • Stockout, backorder, and fill rates by channel and facility.
  • Transfer lead time, on-time rate, and short-ship rate.
  • Receiving and putaway cycle times with exception rates.
  • Pick/pack/ship cycle time and accuracy.
  • Aging inventory, expiry risk, and FEFO compliance.

KPI readiness checklist ​

  • Stock card events captured for all movements, counts, and adjustments with reason codes.
  • Location hierarchy (facility, zone, bin) and ownership/possession states are populated.
  • Receiving, putaway, pick, pack, ship, and transfer timestamps are captured.
  • Exceptions (damage, loss, QC, quarantine) are recorded with dispositions.
  • Cost changes and landed-cost adjustments are recorded as stock card events.

Rebalancing and recalibration ​

  • Transfer and allocation suggestions rebalance stock across facilities based on velocity, safety stock, and capacity.
  • Baseline suggestion logic uses replenishment rules (min/max) plus current availability; recommendations target the destination max and are capped by source availability, with constraints explaining limiting factors.
  • A scheduled replenishment sweep can auto-record pick-face replenishment movements for active rules (idempotent per time window), skipping rules without overstock bins or sufficient stock.
  • Intra-facility re-slotting recalibrates pick-face vs overstock based on pick frequency.
  • Org-level recalibration sets safety stock, min/max, and target weeks of supply.
  • Rebalancing respects policy guardrails (min/max, shelf-life, capacity, ownership).

Downstream accounting and integration capture ​

  • Every inventory event captures org, facility, channel (when applicable), ownership vs possession, SKU, qty, unit cost, timestamps, reason codes, and source references.
  • Stock card events are immutable for firmed transactions and traceable to originating records.
  • Cost basis includes landed costs (freight, tariffs, handling) and transfer-related costs when configured.
  • Cost changes are recorded as first-class stock card events with actor, reason, and references.
  • Events include optional cost-centre attribution for billing and audit.

Comments and inbox ​

  • Every inventory record supports comments, threads, and attachments with revision history.
  • Exceptions generate inbox notifications for the relevant team.

Governance and roles ​

  • Facility-scoped operational roles (ics_* roles) with explicit facility grants for members.
  • Transfer approvals require designated approver roles (ics_transfer_approve) when thresholds are exceeded.
  • Optional no-self-approval rules can be enabled for high-risk transfers.
  • Cost visibility is restricted to cost_view (facility) or finance_audit (org-wide).
  • Owners have implicit facility access.
  • Role grants can be permanent, time-bounded, or scheduled.

Relationships and data flow ​

  • PVM supplies variant identity and product attributes.
  • PCM receiving updates create stock movements in ICS.
  • SCM fulfillment consumes and updates stock availability in ICS.
  • PPM pricing does not alter ICS stock truth but may be referenced for valuation.
  • Accounting readiness consumes ICS events for valuation and audit.

Example scenarios and acceptance criteria ​

Scenario 1: Partial receipt with damage and QC ​

  • A partial shipment arrives; one carton is damaged.
  • QC quarantines the damaged items and releases the rest to available stock.
  • Stock card records both the receipt and the quarantine decision with reason codes.
  • Acceptance: available stock matches released qty; quarantined stock is isolated; audit trail is complete.

Scenario 2: Transfer with in-transit loss ​

  • A transfer is initiated between facilities and marked in-transit.
  • Destination confirms a short receipt; loss is recorded with reason.
  • Stock card includes transfer, in-transit, receipt, and adjustment events.
  • Acceptance: in-transit is cleared; destination stock is accurate; loss is auditable.

Scenario 3: Cycle count discrepancy ​

  • A cycle count finds variance beyond tolerance.
  • Recount is required; final adjustment is recorded with actor and comment.
  • Acceptance: stock card shows both count events and final adjustment; variance is traceable.

Scenario 4: Transfer recommendation vs execution ​

  • The system recommends transferring stock based on velocity, safety stock, and capacity limits.
  • The recommendation includes rationale, constraints triggered, and suggested quantities.
  • An operator approves a transfer request with adjusted quantities.
  • Acceptance: recommendations do not change stock; the approved transfer creates the state change and links back to the recommendation.

Scenario 5: Multi-shipment transfer with partial receipt ​

  • A transfer request is fulfilled by two shipments.
  • One shipment is delayed and the other arrives short.
  • Receiving reconciles partial receipts and records exceptions.
  • Acceptance: shipment statuses are tracked independently; exception counts are visible per shipment; in-transit is cleared on receipt; stock card records all events with reasons.

Scenario 6: Allocation suggestion with cross-channel impact ​

  • A facility is low on stock for a high-priority channel.
  • A suggestion is generated that accounts for space limits and cross-channel cannibalization risk.
  • Acceptance: the suggestion explains the trade-offs and respects channel priorities and capacity constraints.

Scenario 7: Consignment sale and settlement ​

  • A facility receives consigned inventory (possess-not-own) from a vendor.
  • Items are sold; ICS decrements possessed stock and records a consignment consumption event.
  • Acceptance: owned stock is unchanged; possession is reduced; settlement references link to the sale and vendor.

Scenario 8: Recall quarantine and release ​

  • A lot/serial is flagged as recall/stop-sale for the facility’s region.
  • ICS quarantines the affected stock across bins and excludes it from availability.
  • Acceptance: availability excludes quarantined stock; stock card records quarantine and release with policy references.