README

SlotFlow is a deterministic PHP engine for inventory and commerce operations that model quantity movement across an explicit multidimensional state space.

Mental Model

Think of SlotFlow as a constrained routing engine:

• each slot is a node in a graph
• each edge is an allowed movement
• a flow is an ordered movement definition

When you request a quantity movement, SlotFlow:

1. finds valid edges from the current state
2. orders them according to your policies
3. moves as much as possible
4. carries the remainder to the next options

SlotFlow makes quantity movements explicit, deterministic, and auditable.

SlotFlow is intentionally not a full ERP, OMS, or WMS. It is the lower-level engine those systems can build on for stock movement, allocation, backorders, and delivery promises.

Core Concepts

• A Slot is one concrete state such as wh1.FP.fs.
  • The special nil slot represents outside-of-space flow: both source, sink, and effectively /dev/null.
• A SlotSpace is the finite universe of valid slots generated from named dimensions.
• An Edge is an allowed movement between two slots.
• A Flow is an ordered movement definition that defines how movement is attempted.
• A QuantityState stores the current quantity distribution for one subject across the slot space.
• MovementEngine executes a requested quantity against current state and returns movement events plus any remainder.

At its core, SlotFlow acts as a declarative inventory-movement engine over a constrained state space.

Notes

• Flows can be instantiated independently, but are typically registered on a SlotSpace and referenced by name during execution.
• Flows can be reversed with reverseIf() and parameterized, allowing a single definition to adapt to different execution contexts.
• Cascade and Inventory remain available as deprecated compatibility aliases for Flow and QuantityState.

When SlotFlow shines

SlotFlow is a good fit when:

• quantities exist in multiple states or locations
• movement rules are non-trivial or evolving
• allocation must be deterministic and explainable
• you need to model backorders or delivery promises
• multi-line orders may release in full, partial, threshold-based, or priority-based shipments
• you need auditability (ledger-style tracking)

It is likely overkill for simple stock counters or single-location systems.

Install

SlotFlow currently requires PHP 8.1 or newer.

composer require nandan108/slot-flow

## Licensing

SlotFlow is dual-licensed:

- `GPL-2.0-or-later` for open-source use under GPL-compatible terms
- a separate commercial license for proprietary or otherwise non-GPL-compatible use

See [LICENSE](LICENSE), [LICENSE-GPL-2.0-or-later](LICENSE-GPL-2.0-or-later), and [LICENSE-SlotFlow-Commercial](LICENSE-SlotFlow-Commercial).

Minimal Example

use Nandan108\SlotFlow\Flow;
use Nandan108\SlotFlow\MovementEngine;
use Nandan108\SlotFlow\Policies\DimensionPriority;
use Nandan108\SlotFlow\QuantityState;
use Nandan108\SlotFlow\SlotSpace;

$space = SlotSpace::define([
    'loc' => ['sup', 'wh1'],
    'stt' => ['fs', 'res', 'sd'],
])
->flow('reserve', static fn (Flow $flow) => $flow
    ->move(['stt' => 'fs'], ['stt' => 'res'])
    ->orderBy(new DimensionPriority(['loc' => ['wh*', 'sup']]))
);

$inventory = new QuantityState($space, [
    ['wh1.fs', 5],
    ['sup.fs', 10],
]);

$result = (new MovementEngine())->execute(
    inventory: $inventory,
    space: $space,
    cascade: 'reserve',
    quantity: 6,
    subject: 'SKU-123',
);

MovementEngine::execute() accepts either a Flow object or the name of a flow registered on the provided SlotSpace. Named execution is often the cleaner option once your flows are part of the modeled space.

For backward compatibility, the named argument on MovementEngine::execute() is still called cascade.

How the flow behaves

In this example:

• the engine first consumes wh1.fs → wh1.res
• then falls back to sup.fs → sup.res

So 5 units move from wh1.fs to wh1.res, then the remaining 1 unit moves from sup.fs to sup.res.

Slightly more advanced routing

Flows can express real-world fallback strategies, including backorders.

$space = SlotSpace::define([
    'loc' => ['sup','wh1', 'wh2'], // sup: supplier, wh*: our warehouses
    'own' => ['S', 'P'],           // S: supplier-owned / P: purchased
    'stt' => ['fs', 'res', 'sd'],  // fs: for-sale, res: reserved, sd: sold
])
->flow('backorder', static fn (Flow $flow) => $flow
    // prioritize stock we already own
    ->move(['stt' => 'fs', 'own' => 'P'], ['stt' => 'res'])

    // prefer warehouse over supplier
    ->orderBy(new DimensionPriority(['loc' => ['wh*', 'sup'],]))

    // fallback: create supplier-owned reservation (backorder)
    // this represents stock that will be ordered from the supplier
    // Note: could also be written ->create('sup.S.res') or ->create(['sup','S','res'])
    ->create(['loc' => 'sup', 'own' => 'S', 'stt' => 'res'])
    // disallow backorders beyond 100
    ->constraint(static fn (MovementEdge $edge, FlowContext $ctx): int|float =>
        max(0, 100 - $ctx->inventory->getSum('sup.S.res|sd')))
);

This flow encodes a common allocation policy:

1. use purchased stock first
2. prefer stock already in your warehouses
3. if insufficient, create a supplier reservation (backorder)
4. but never let open supplier backorders (sup.S.res|sd) exceed 100 units

This makes backordering an explicit, deterministic part of the flow.

The same policy also supports alternatives such as 'wh1|wh2', because priority entries are resolved through the configured slot codec before ranking edges. All values matched by the same entry share the same priority tier.

Registered flow names pair especially well with parameterized templates: you define the flow once on the SlotSpace, then execute it by name with different params depending on the request.

Delivery Promises And Order Release

SlotFlow can also plan timed delivery promises.

• ScheduleRequest and EarliestArrivalSolver build one timed movement schedule for one subject quantity
• Demand, DemandLine, DemandScheduleRequest, and DemandScheduler compose many subject schedules into one order-level promise
• release policies such as PartialShipmentPolicy, FullShipmentPolicy, ThresholdReleasePolicy, and PriorityReleasePolicy decide how ready lines turn into shipments
• timed slot spaces can also apply dispatch calendars, for example cutoff-time or no-weekend dispatch rules

Execution Output

SlotFlow computes movement. It does not persist it.

It produces explicit, inspectable results that you can store, audit, or replay.

The main result shapes are:

• MovementResult::deltas() for net per-slot current-state deltas
• MovementResult::ledgerEntries($context) for append-only movement records
• MovementSchedule::$steps, MovementSchedule::$milestones, and MovementSchedule::deltas() for time-based planning output
• DemandSchedule::$lines and DemandSchedule::$shipments for multi-line order promise output
• QuantityStateBatch::deltas() and QuantityStateBatch::ledgerEntries($context) for the same outputs across many subjects

Terminology

Current core terminology:

• Flow: generic ordered movement definition
• QuantityState: quantity distribution for one subject
• QuantityStateBatch: grouped quantity states for batch execution
• QuantityStateDelta: one net per-slot quantity delta

Deprecated compatibility aliases:

• Cascade -> Flow
• Inventory -> QuantityState
• InventoryBatch -> QuantityStateBatch
• InventoryMutation -> QuantityStateDelta

Guide

• Guide: core SlotFlow concepts, execution, and batch processing
• Time And Planning Guide: timeless planning, timed slot spaces, earliest-arrival scheduling, and demand scheduling
• Commerce Example: a fuller e-commerce flow model
• v0.2.0 notes: summary of the timed layer, planners, and demand scheduling additions
• Changelog: release-by-release project history
• Generated API docs: https://nandan108.github.io/slot-flow

Origin

SlotFlow originates from a real-world inventory system I developed in 2017 for a production e-commerce platform.

That system handled:

• multi-location stock allocation
• inbound stock and delivery promise computation
• reservation and booking flows
• partial shipment tracking
• movement logging (ledger)

Over time, the limitations of a tightly coupled implementation became clear: movement rules, state representation, and execution logic were all intertwined.

SlotFlow is an extraction of its core ideas as a composable engine for inventory movement and promise calculation.

For historical reference, the original implementation is preserved here: 👉 docs/history/original-MPB-InventoryEngine.php

Quality

• 99% automated test coverage
• Psalm level 1 clean
• CI runs Psalm, coverage, and phpDocumentor on PHP 8.1
• CI runs PHPUnit on PHP 8.1, 8.2, 8.3, 8.4, and 8.5
• Generated API docs published from source via phpDocumentor

Release Status

v0.2.0 is the first release that adds a full timed planning layer:

• TimeAxis, TimedSlotSpace, and timed edges
• MovementPlanner for timeless path planning
• ScheduleRequest and EarliestArrivalSolver for timed planning
• DemandScheduler and shipment release policies for order-level promise calculation

The core execution engine remains the most mature part of the library. The timed and demand-scheduling APIs are documented and tested, but they should still be expected to evolve as more real-world use cases are applied to them.

License

SlotFlow is dual-licensed under GPL-2.0-or-later or the SlotFlow commercial license. See LICENSE, LICENSE-GPL-2.0-or-later, LICENSE-SlotFlow-Commercial, and NOTICE.

Organizations using SlotFlow in proprietary or otherwise non-GPL-compatible software must obtain a separate commercial license. Reduced-fee or no-fee commercial licenses may be available on request for qualified nonprofit, humanitarian, and public-interest organizations.