# Limit-Order Lifecycle State Machine

`D12-F04-A01` · Matching Engines and Venue Logic → Order Lifecycle and Queue State · archetype `record-transform` · difficulty 3/5 · verification **verified**

Full page: https://docs.thefintechbuilder.com/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/limit-order-lifecycle-state-machine/
Agent skill: `npx skills add IslamBaraka90/Fintech-Algorithms-Library` — https://docs.thefintechbuilder.com/guides/agent-skill/

## Install and import

```bash
npm install fintech-algorithms
```

```ts
import { limitOrderLifecycle } from "fintech-algorithms/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/limit-order-lifecycle-state-machine";
```

## Signature

```ts
limitOrderLifecycle(orderIdRaw, orderQuantityRaw, eventsRaw)
```

Replays an order's events into its state history — new, partially filled, replaced, cancelled, done. The value is rejecting *invalid* transitions: a fill after a cancel is a bug somewhere upstream, and it must not be absorbed silently.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `orderIdRaw` | `string` | yes | The order being tracked. |
| `orderQuantityRaw` | `number` | yes | Original order quantity. · min: 1, integer: true |
| `eventsRaw` | `Event[]` | yes | Lifecycle events in sequence. |

## Returns

`{ states, final_state, invalid_transitions, filled, residual, … }`

The state path with any invalid transitions named rather than absorbed.

## Errors

- When an event references a different order id — throws

## Complexity

Time `O(events)`, space `O(events)`.

## Worked example

Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

### Input

`orderIdRaw`:

```json
"L-100"
```

`orderQuantityRaw`:

```json
1000
```

`eventsRaw`:

```json
[
  {
    "type": "accept"
  },
  {
    "type": "fill",
    "quantity": 300,
    "price": 100
  },
  {
    "type": "fill",
    "quantity": 500,
    "price": 100.01
  }
]
```

Showing 3 of 4 elements.

### Call

```ts
limitOrderLifecycle(orderIdRaw, orderQuantityRaw, eventsRaw)
```

### Returns

object with 11 fields: model, order_id, order_quantity, cumulative_quantity, leaves_quantity, average_fill_price, execution_count, status, …

```json
{
  "model": "accepted-order-lifecycle-state-machine",
  "order_id": "L-100",
  "order_quantity": 1000,
  "cumulative_quantity": 1000,
  "leaves_quantity": 0,
  "average_fill_price": 100.009,
  "execution_count": 3,
  "status": "filled",
  "terminal": true,
  "transitions": [
    {
      "event_index": 0,
      "event_type": "accept",
      "before_status": "pending-new",
      "after_status": "new",
      "cumulative_quantity": 0,
      "leaves_quantity": 1000
    },
    {
      "event_index": 1,
      "event_type": "fill",
      "before_status": "new",
      "after_status": "partially-filled",
      "cumulative_quantity": 300,
      "leaves_quantity": 700
    },
    {
      "event_index": 2,
      "event_type": "fill",
      "before_status": "partially-filled",
      "after_status": "partially-filled",
      "cumulative_quantity": 800,
      "leaves_quantity": 200
    }
  ],
  "state": "filled"
}
```

## Other exports

`cancelReplacePriority`, `partialFillResidual`, `queuePositionAheadVolume`, `icebergReplenishment`, `marketableOrderSweep`, `calculate`. Every module additionally exports `run` as an alias of its primary
function, and a `meta` object carrying its catalog id, domain, family, shape and article URL.

## Verification and provenance

Tier: **verified** (via D).

The worked example below is the figure published in this algorithm's article, replayed and asserted by the test suite on every build. The arithmetic cannot drift without the build failing.

Both tiers guarantee the signature. Full explanation: https://docs.thefintechbuilder.com/guides/verification/

Generated from the docs.json payload shipped inside fintech-algorithms@0.13.1.
The signature and parameter list are checked against the compiled implementation at build time,
so a description that contradicts the code fails the build rather than reaching this file.

## Links

- Article (how it works, step by step): https://thefintechbuilder.com/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/limit-order-lifecycle-state-machine/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/limit-order-lifecycle-state-machine/impl.ts
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/matching-engines-and-venue-logic/llms.txt