{
  "version": 1,
  "state": "009-order-management-matcher",
  "title": "Model an order before it becomes a trade",
  "purpose": "An intention to buy may remain unfulfilled, fill in pieces, or be canceled. For developers moving beyond immediate trade booking, this chapter introduces the order lifecycle and shows why an order\u2019s requested quantity cannot be treated as an executed position.",
  "entryAssumptions": "The pricing state shows quotes and can book trades, but has no persistent pending-order lifecycle.",
  "concepts": [
    "An order expresses an intention. A fill executes some quantity. A limit caps a buy price or sets a sell floor; partial fills leave a remainder."
  ],
  "runtimePrerequisites": "Use the state quickstart for tool versions, generation, start and stop commands. Run one local state at a time because ports and generated output directories are shared.",
  "entryMode": "combined",
  "transitions": [
    {
      "from": "008-pricing-awareness-market-data",
      "carriesForward": "Stream simulated market data and use price awareness while retaining the booking workflow.",
      "motivation": "The pricing state shows quotes and can book trades, but has no persistent pending-order lifecycle.",
      "increment": "Introduce limit orders, matching and fills while keeping orders distinct from executed trades.",
      "objectiveIds": [
        "trace-increment",
        "interpret-evidence"
      ],
      "evidence": "A resting order is not a booked trade. A qualifying tick can trigger a fill; the matcher policy is a demonstration, not an exchange matching engine. Cancellation of the remainder does not reverse an already booked fill. Large quantities can produce partial fills under the demonstration policy."
    }
  ],
  "before": "The pricing state shows quotes and can book trades, but has no persistent pending-order lifecycle.",
  "after": "Introduce limit orders, matching and fills while keeping orders distinct from executed trades.",
  "objectives": [
    {
      "id": "trace-increment",
      "outcome": "Distinguish a resting order, a fill and a booked trade by reconciling their identifiers and quantities."
    },
    {
      "id": "interpret-evidence",
      "outcome": "Explain the evidence boundary: Cancellation of the remainder does not reverse an already booked fill. Large quantities can produce partial fills under the demonstration policy."
    }
  ],
  "walkthrough": [
    {
      "id": "observe",
      "objectiveIds": [
        "trace-increment"
      ],
      "availability": "available",
      "action": "Start this state, choose a ticker with current quotes, and create a small buy limit order below the displayed market. Record its identifier and remaining quantity. Compare the order view with the trade view. Then create an executable small limit order and observe the matcher and resulting fill.",
      "expected": "A resting order is not a booked trade. A qualifying tick can trigger a fill; the matcher policy is a demonstration, not an exchange matching engine.",
      "references": [
        "/specs/order-management-matcher/quickstart",
        "/specs/order-management-matcher/system/architecture",
        "/specs/order-management-matcher/system/runtime-topology"
      ]
    },
    {
      "id": "challenge",
      "objectiveIds": [
        "interpret-evidence"
      ],
      "availability": "available",
      "action": "Create an unfilled order and cancel it. Record its status, filled and remaining quantities and compare trade records before and after. Then, as a reading exercise, apply the documented partial-fill policy to a hypothetical order of 1200 with 600 already filled and predict what canceling the remainder should preserve.",
      "expected": "Unfilled cancellation should produce CANCELED with no new booked fill. The reading exercise predicts preservation of previously booked fills, but does not verify partial-fill cancellation at runtime.",
      "references": [
        "/specs/order-management-matcher/spec",
        "/specs/order-management-matcher/contracts/contract-delta"
      ]
    }
  ],
  "assessments": [
    {
      "objectiveIds": [
        "trace-increment",
        "interpret-evidence"
      ],
      "question": "How would you reconcile an order that is partially filled and then canceled?",
      "guidance": "Account for filled quantity in executions and positions, and the unfilled remainder in the canceled order. Do not treat the original requested quantity as fully traded. Label a hypothetical reconciliation as reading practice. Demonstrating partial-fill cancellation requires actual before-and-after order, trade and position records."
    }
  ],
  "limitations": [
    "Cancellation of the remainder does not reverse an already booked fill. Large quantities can produce partial fills under the demonstration policy.",
    "This is an educational local demonstration. Passing its checks does not establish production readiness, financial settlement, or correctness under every failure mode."
  ],
  "coaching": [
    {
      "objectiveIds": [
        "trace-increment",
        "interpret-evidence"
      ],
      "diagnosticQuestion": "How are requested quantity, filled quantity and remaining quantity related?",
      "predictionPrompt": "Predict which records should exist for a resting limit order before it receives a qualifying tick.",
      "hints": [
        "Start by separating the order identifier from execution identifiers.",
        "Reconcile requested quantity with filled quantity and the canceled or still-open remainder."
      ],
      "misconception": "Creating or canceling an order creates or reverses a trade for the entire requested quantity.",
      "evidenceToRequest": "Ask for the order lifecycle and quantities plus associated executions/positions, and have the learner explain any partially filled remainder."
    }
  ]
}