{
  "id": "inventory-scenarios-optimize",
  "name": "Exact finite-scenario inventory order",
  "description": "Enumerate every admissible one-period order quantity and minimize exact expected purchase, fixed-order, leftover and unmet-demand costs under caller-supplied demand scenarios. Return all optimal quantities and scenario arithmetic; no demand forecast, service guarantee or order placement.",
  "category": "workflow-assurance",
  "priceUsd": "0.008",
  "pricingStatus": "proposed-unverified",
  "pricing": {
    "unit": "one successful operation call",
    "proposedNominalUsd": "0.008",
    "sixDecimalTokenBaseUnits": "8000",
    "subscription": false,
    "includesPayerWalletOrNetworkFees": false,
    "liveQuoteVerified": false,
    "condition": "Actual SDK challenge is authoritative only within the caller's explicit authorization; configured six-decimal token peg is an operator assertion, not a conversion guarantee."
  },
  "intents": [
    "Optimize a single-period reorder quantity under explicit demand scenarios",
    "Compare order multiples and minimum-positive-order constraints with holding and shortage costs"
  ],
  "whenToUse": [
    "Supply integer inventory and demand in one unit, positive relative scenario probabilities and nonnegative cost assumptions",
    "All replenishment arrives before demand and every positive order follows the declared multiple and minimum"
  ],
  "whenNotToUse": [
    "Forecasting, multi-period inventory, uncertain lead time, backorder carryover, shelf life, multiple products or capacity coupling",
    "Real procurement, inventory availability checks, service-level promises or profit optimization",
    "Investment advice, high-impact decisions about people, or validating the truth of caller assumptions"
  ],
  "capabilities": [
    "Exact exhaustive expected-cost optimum across at most 512 legal quantities; zero order is always permitted",
    "Complete candidate expected/worst cost table, all exact ties, and smallest-quantity tie break",
    "Chosen-scenario shortage, leftover and normalized probabilities; existing on-hand purchase cost is sunk and excluded",
    "Stockout probability applies only to the supplied finite scenario model and is not a calibrated real-world risk estimate",
    "Exact bounded supplied-data arithmetic; no network, clock, randomness or external action"
  ],
  "related": [
    "decision-scenarios-analyze",
    "decimal-distribution-summarize"
  ],
  "limits": {
    "inputBytes": 48000,
    "outputBytes": 192000,
    "jsonNodes": 8000,
    "depth": 12,
    "scenarios": 32,
    "orderCandidates": 512,
    "maximumCandidateScenarioEvaluations": 16384,
    "maximumChosenScenarioEvaluations": 32,
    "quantityMaximum": 1000000,
    "decimalIntegerDigits": 12,
    "decimalFractionDigits": 6,
    "probabilityWeightDigits": 9
  },
  "errorCodes": [
    "INPUT_LIMIT",
    "OUTPUT_LIMIT",
    "COMPLEXITY_LIMIT",
    "INVALID_JSON",
    "INVALID_NUMBER",
    "INVALID_UNICODE",
    "UNSAFE_KEY",
    "INVALID_INPUT",
    "DUPLICATE_ID",
    "CANDIDATE_LIMIT"
  ],
  "requirementsProfile": {
    "format": "declared-requirements-v1",
    "facts": {
      "execution.suppliedCode": false,
      "execution.remoteMutation": false,
      "execution.llmInference": false,
      "execution.paidMcp": false,
      "verification.semanticTruth": false,
      "verification.sourceAuthenticity": false,
      "verification.liveVulnerabilities": false,
      "numbers.arbitraryPrecisionJson": false,
      "numbers.model": "bounded-exact-decimal-strings-and-integer-quantities",
      "privacy.requestBodyPersisted": false,
      "execution.deterministic": true,
      "execution.networkAccess": false,
      "privacy.resultBodyPersisted": false,
      "payment.x402": true,
      "payment.mpp": true,
      "operation.id": "inventory-scenarios-optimize",
      "operation.category": "workflow-assurance",
      "limit.httpRequestBytes": 131072,
      "limit.requestBytes": 48000,
      "limit.responseBytes": 524288,
      "limit.resultBytes": 192000,
      "limit.jsonDepth": 12,
      "limit.jsonNodes": 8000,
      "decision.exactSuppliedDataArithmetic": true,
      "decision.assumptionsVerified": false,
      "decision.externalAction": false,
      "decision.forecastsGenerated": false,
      "decision.realWorldOptimalityGuaranteed": false,
      "decision.maxDecimalIntegerDigits": 12,
      "decision.maxDecimalFractionDigits": 6,
      "decision.profile": "finite-scenario-single-period-inventory-v1",
      "inventory.maxScenarios": 32,
      "inventory.maxOrderCandidates": 512,
      "inventory.exactFiniteExpectedCostOptimum": true,
      "inventory.allExactTies": true,
      "inventory.multiPeriod": false,
      "inventory.procurement": false,
      "inventory.calibratedServiceGuarantee": false,
      "inventory.profitOptimization": false,
      "input.onHand.maximum": 1000000,
      "input.onHand.minimum": 0,
      "input.scenarios.maxItems": 32,
      "input.scenarios.minItems": 1,
      "input.quantityUnit.maxLength": 64,
      "input.quantityUnit.minLength": 1,
      "input.costUnit.maxLength": 64,
      "input.costUnit.minLength": 1
    },
    "unknownPolicy": "Undeclared requirements are unknown, never compatible. Matching declared facts does not establish semantic fit or input validity.",
    "preflight": "/preflight"
  },
  "documentation": "/reference/tools/inventory-scenarios-optimize.md",
  "serviceContract": "/reference/services/inventory-scenarios-optimize.json",
  "errors": [
    {
      "status": 400,
      "meaning": "Malformed JSON, missing/invalid idempotency key, or payment identifier mismatch",
      "retry": "Correct the request before payment"
    },
    {
      "status": 402,
      "meaning": "Payment challenge or rejected payment",
      "retry": "Use official protocol SDK; inspect payment outcome before another payment"
    },
    {
      "status": 409,
      "meaning": "Idempotency conflict, duplicate proof, or PAYMENT_UNCERTAIN",
      "retry": "Keep original key, body, and proof; reconcile uncertainty with operator; never blindly repay"
    },
    {
      "status": 413,
      "meaning": "Input or generated output too large",
      "retry": "Reduce input; no payment attempted for validation failure"
    },
    {
      "status": 415,
      "meaning": "Unsupported media type or compression",
      "retry": "Send uncompressed application/json"
    },
    {
      "status": 422,
      "meaning": "Schema or service-specific semantic validation failure",
      "retry": "Correct input using returned error code; no payment attempted"
    },
    {
      "status": 429,
      "meaning": "Request/payment-attempt rate exceeded",
      "retry": "Wait for rate limit window; preserve existing payment identity"
    },
    {
      "status": 503,
      "meaning": "Payment configuration/provider/state unavailable, or live DNS preparation failed before settlement",
      "retry": "Check readiness; DNS preparation failures may retry the identical key/body/credential only; uncertainty requires reconciliation"
    }
  ],
  "numericPrecision": "JavaScript IEEE-754 numbers; use strings for large integer IDs/exact decimals where the schema accepts strings. No lossless numeric parsing.",
  "paymentWorkflow": {
    "discoveryOnly": false,
    "supportedProtocols": [
      "x402",
      "mpp"
    ],
    "x402": {
      "credentialHeader": "PAYMENT-SIGNATURE",
      "challengeHeader": "PAYMENT-REQUIRED",
      "receiptHeader": "PAYMENT-RESPONSE",
      "version": 2,
      "scheme": "exact",
      "paymentIdentifier": "payment-identifier extension MUST equal the HTTP Idempotency-Key",
      "sdk": "@x402/core with @x402/evm"
    },
    "mpp": {
      "supported": true,
      "credentialHeader": "Authorization",
      "challengeHeader": "WWW-Authenticate",
      "receiptHeader": "Payment-Receipt",
      "method": "tempo",
      "intent": "charge",
      "sdk": "mppx",
      "tokenDecimals": 6
    },
    "steps": [
      "Check configured readiness and the exact service schema",
      "Generate a fresh random Idempotency-Key for this operation; never use a discovery probe fixture for purchases",
      "Send valid input without a credential to obtain the official protocol challenge",
      "Use the official SDK and authorized wallet to fulfill the challenge",
      "Retry only with identical key, body, protocol and credential",
      "On PAYMENT_UNCERTAIN stop and request operator reconciliation; never blindly pay again"
    ],
    "versionedRetries": "Request fingerprint includes service release version. Retries across a version upgrade can conflict; coordinate upgrades outside the 24-hour replay window and reconcile pending attempts.",
    "docs": "/llms.txt"
  },
  "method": "POST",
  "paths": {
    "x402": "/v1/x402/inventory-scenarios-optimize",
    "mpp": "/v1/mpp/inventory-scenarios-optimize"
  },
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "onHand": {
        "type": "integer",
        "minimum": 0,
        "maximum": 1000000
      },
      "scenarios": {
        "minItems": 1,
        "maxItems": 32,
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "demand": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000
            },
            "probabilityWeight": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,8}$"
            }
          },
          "required": [
            "id",
            "demand",
            "probabilityWeight"
          ],
          "additionalProperties": false
        }
      },
      "order": {
        "type": "object",
        "properties": {
          "minimumPositive": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000
          },
          "maximum": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000
          },
          "multiple": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000
          }
        },
        "required": [
          "minimumPositive",
          "maximum",
          "multiple"
        ],
        "additionalProperties": false
      },
      "costs": {
        "type": "object",
        "properties": {
          "purchasePerUnit": {
            "type": "string",
            "pattern": "^(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,6})?$"
          },
          "holdingPerUnit": {
            "type": "string",
            "pattern": "^(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,6})?$"
          },
          "shortagePerUnit": {
            "type": "string",
            "pattern": "^(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,6})?$"
          },
          "fixedPositiveOrder": {
            "type": "string",
            "pattern": "^(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,6})?$"
          }
        },
        "required": [
          "purchasePerUnit",
          "holdingPerUnit",
          "shortagePerUnit",
          "fixedPositiveOrder"
        ],
        "additionalProperties": false
      },
      "quantityUnit": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64
      },
      "costUnit": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64
      }
    },
    "required": [
      "onHand",
      "scenarios",
      "order",
      "costs",
      "quantityUnit",
      "costUnit"
    ],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": [
      "operation",
      "version",
      "result",
      "provenance"
    ],
    "properties": {
      "operation": {
        "const": "inventory-scenarios-optimize",
        "type": "string"
      },
      "version": {
        "const": "0.29.0",
        "type": "string"
      },
      "result": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "profile": {
            "type": "string",
            "const": "finite-scenario-single-period-inventory-v1"
          },
          "externalRequests": {
            "type": "number",
            "const": 0
          },
          "execution": {
            "type": "boolean",
            "const": false
          },
          "assumptionsVerified": {
            "type": "boolean",
            "const": false
          },
          "status": {
            "type": "string",
            "const": "optimal"
          },
          "quantityUnit": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "costUnit": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "orderQuantity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000
          },
          "availableQuantity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000000
          },
          "expectedCost": {
            "type": "object",
            "properties": {
              "numerator": {
                "type": "string",
                "pattern": "^(?:0|[1-9][0-9]*)$"
              },
              "denominator": {
                "type": "string",
                "pattern": "^[1-9][0-9]*$"
              }
            },
            "required": [
              "numerator",
              "denominator"
            ],
            "additionalProperties": false
          },
          "worstCost": {
            "type": "object",
            "properties": {
              "numerator": {
                "type": "string",
                "pattern": "^(?:0|[1-9][0-9]*)$"
              },
              "denominator": {
                "type": "string",
                "pattern": "^[1-9][0-9]*$"
              }
            },
            "required": [
              "numerator",
              "denominator"
            ],
            "additionalProperties": false
          },
          "expectedShortage": {
            "type": "object",
            "properties": {
              "numerator": {
                "type": "string",
                "pattern": "^(?:0|[1-9][0-9]*)$"
              },
              "denominator": {
                "type": "string",
                "pattern": "^[1-9][0-9]*$"
              }
            },
            "required": [
              "numerator",
              "denominator"
            ],
            "additionalProperties": false
          },
          "expectedLeftover": {
            "type": "object",
            "properties": {
              "numerator": {
                "type": "string",
                "pattern": "^(?:0|[1-9][0-9]*)$"
              },
              "denominator": {
                "type": "string",
                "pattern": "^[1-9][0-9]*$"
              }
            },
            "required": [
              "numerator",
              "denominator"
            ],
            "additionalProperties": false
          },
          "suppliedScenarioStockoutProbability": {
            "type": "object",
            "properties": {
              "numerator": {
                "type": "string",
                "pattern": "^(?:0|[1-9][0-9]*)$"
              },
              "denominator": {
                "type": "string",
                "pattern": "^[1-9][0-9]*$"
              }
            },
            "required": [
              "numerator",
              "denominator"
            ],
            "additionalProperties": false
          },
          "optimalOrderQuantities": {
            "minItems": 1,
            "maxItems": 512,
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000
            }
          },
          "candidates": {
            "minItems": 1,
            "maxItems": 512,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "orderQuantity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 1000000
                },
                "expectedCost": {
                  "type": "object",
                  "properties": {
                    "numerator": {
                      "type": "string",
                      "pattern": "^(?:0|[1-9][0-9]*)$"
                    },
                    "denominator": {
                      "type": "string",
                      "pattern": "^[1-9][0-9]*$"
                    }
                  },
                  "required": [
                    "numerator",
                    "denominator"
                  ],
                  "additionalProperties": false
                },
                "worstCost": {
                  "type": "object",
                  "properties": {
                    "numerator": {
                      "type": "string",
                      "pattern": "^(?:0|[1-9][0-9]*)$"
                    },
                    "denominator": {
                      "type": "string",
                      "pattern": "^[1-9][0-9]*$"
                    }
                  },
                  "required": [
                    "numerator",
                    "denominator"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "orderQuantity",
                "expectedCost",
                "worstCost"
              ],
              "additionalProperties": false
            }
          },
          "chosenScenarios": {
            "minItems": 1,
            "maxItems": 32,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scenarioId": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 64
                },
                "probability": {
                  "type": "object",
                  "properties": {
                    "numerator": {
                      "type": "string",
                      "pattern": "^(?:0|[1-9][0-9]*)$"
                    },
                    "denominator": {
                      "type": "string",
                      "pattern": "^[1-9][0-9]*$"
                    }
                  },
                  "required": [
                    "numerator",
                    "denominator"
                  ],
                  "additionalProperties": false
                },
                "demand": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 1000000
                },
                "shortage": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 1000000
                },
                "leftover": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 2000000
                },
                "cost": {
                  "type": "object",
                  "properties": {
                    "numerator": {
                      "type": "string",
                      "pattern": "^(?:0|[1-9][0-9]*)$"
                    },
                    "denominator": {
                      "type": "string",
                      "pattern": "^[1-9][0-9]*$"
                    }
                  },
                  "required": [
                    "numerator",
                    "denominator"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "scenarioId",
                "probability",
                "demand",
                "shortage",
                "leftover",
                "cost"
              ],
              "additionalProperties": false
            }
          },
          "model": {
            "type": "object",
            "properties": {
              "period": {
                "type": "string",
                "const": "single-period"
              },
              "replenishment": {
                "type": "string",
                "const": "all-ordered-units-before-demand"
              },
              "unmetDemand": {
                "type": "string",
                "const": "penalized-without-carryover"
              },
              "demandSource": {
                "type": "string",
                "const": "caller-supplied-finite-scenarios"
              },
              "probabilityModel": {
                "type": "string",
                "const": "normalized-positive-relative-weights"
              }
            },
            "required": [
              "period",
              "replenishment",
              "unmetDemand",
              "demandSource",
              "probabilityModel"
            ],
            "additionalProperties": false
          },
          "tieBreak": {
            "type": "string",
            "const": "smallest-order-quantity; all-optimal-quantities-also-returned"
          }
        },
        "required": [
          "profile",
          "externalRequests",
          "execution",
          "assumptionsVerified",
          "status",
          "quantityUnit",
          "costUnit",
          "orderQuantity",
          "availableQuantity",
          "expectedCost",
          "worstCost",
          "expectedShortage",
          "expectedLeftover",
          "suppliedScenarioStockoutProbability",
          "optimalOrderQuantities",
          "candidates",
          "chosenScenarios",
          "model",
          "tieBreak"
        ],
        "additionalProperties": false
      },
      "provenance": {
        "type": "object",
        "required": [
          "inputSha256",
          "outputSha256",
          "deterministic",
          "externalRequests"
        ],
        "properties": {
          "inputSha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "outputSha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "deterministic": {
            "const": true
          },
          "externalRequests": {
            "const": 0
          }
        }
      }
    },
    "additionalProperties": false
  },
  "exampleInput": {
    "onHand": 3,
    "scenarios": [
      {
        "id": "low",
        "demand": 4,
        "probabilityWeight": "1"
      },
      {
        "id": "normal",
        "demand": 8,
        "probabilityWeight": "2"
      },
      {
        "id": "high",
        "demand": 12,
        "probabilityWeight": "1"
      }
    ],
    "order": {
      "minimumPositive": 4,
      "maximum": 12,
      "multiple": 2
    },
    "costs": {
      "purchasePerUnit": "2",
      "holdingPerUnit": "1",
      "shortagePerUnit": "7",
      "fixedPositiveOrder": "3"
    },
    "quantityUnit": "units",
    "costUnit": "caller-defined cost units"
  },
  "exampleResponse": {
    "operation": "inventory-scenarios-optimize",
    "version": "0.29.0",
    "result": {
      "profile": "finite-scenario-single-period-inventory-v1",
      "externalRequests": 0,
      "execution": false,
      "assumptionsVerified": false,
      "status": "optimal",
      "quantityUnit": "units",
      "costUnit": "caller-defined cost units",
      "orderQuantity": 6,
      "availableQuantity": 9,
      "expectedCost": {
        "numerator": "22",
        "denominator": "1"
      },
      "worstCost": {
        "numerator": "36",
        "denominator": "1"
      },
      "expectedShortage": {
        "numerator": "3",
        "denominator": "4"
      },
      "expectedLeftover": {
        "numerator": "7",
        "denominator": "4"
      },
      "suppliedScenarioStockoutProbability": {
        "numerator": "1",
        "denominator": "4"
      },
      "optimalOrderQuantities": [
        6
      ],
      "candidates": [
        {
          "orderQuantity": 0,
          "expectedCost": {
            "numerator": "35",
            "denominator": "1"
          },
          "worstCost": {
            "numerator": "63",
            "denominator": "1"
          }
        },
        {
          "orderQuantity": 4,
          "expectedCost": {
            "numerator": "24",
            "denominator": "1"
          },
          "worstCost": {
            "numerator": "46",
            "denominator": "1"
          }
        },
        {
          "orderQuantity": 6,
          "expectedCost": {
            "numerator": "22",
            "denominator": "1"
          },
          "worstCost": {
            "numerator": "36",
            "denominator": "1"
          }
        },
        {
          "orderQuantity": 8,
          "expectedCost": {
            "numerator": "24",
            "denominator": "1"
          },
          "worstCost": {
            "numerator": "26",
            "denominator": "1"
          }
        },
        {
          "orderQuantity": 10,
          "expectedCost": {
            "numerator": "28",
            "denominator": "1"
          },
          "worstCost": {
            "numerator": "32",
            "denominator": "1"
          }
        },
        {
          "orderQuantity": 12,
          "expectedCost": {
            "numerator": "34",
            "denominator": "1"
          },
          "worstCost": {
            "numerator": "38",
            "denominator": "1"
          }
        }
      ],
      "chosenScenarios": [
        {
          "scenarioId": "high",
          "probability": {
            "numerator": "1",
            "denominator": "4"
          },
          "demand": 12,
          "shortage": 3,
          "leftover": 0,
          "cost": {
            "numerator": "36",
            "denominator": "1"
          }
        },
        {
          "scenarioId": "low",
          "probability": {
            "numerator": "1",
            "denominator": "4"
          },
          "demand": 4,
          "shortage": 0,
          "leftover": 5,
          "cost": {
            "numerator": "20",
            "denominator": "1"
          }
        },
        {
          "scenarioId": "normal",
          "probability": {
            "numerator": "1",
            "denominator": "2"
          },
          "demand": 8,
          "shortage": 0,
          "leftover": 1,
          "cost": {
            "numerator": "16",
            "denominator": "1"
          }
        }
      ],
      "model": {
        "period": "single-period",
        "replenishment": "all-ordered-units-before-demand",
        "unmetDemand": "penalized-without-carryover",
        "demandSource": "caller-supplied-finite-scenarios",
        "probabilityModel": "normalized-positive-relative-weights"
      },
      "tieBreak": "smallest-order-quantity; all-optimal-quantities-also-returned"
    },
    "provenance": {
      "inputSha256": "e9bd47771b7ab5ca743bc425d2ff7a74a1233428d38fead34e0639f779c794c2",
      "outputSha256": "11a18148d92b8f02fda0cf2acaf2441beb31688c28e80deaeceba054958ad0a5",
      "deterministic": true,
      "externalRequests": 0
    }
  },
  "requiredHeaders": {
    "Content-Type": "application/json",
    "Idempotency-Key": "random 16–128 character operation identifier"
  },
  "fixedExample": "/reference/examples/inventory-scenarios-optimize.json",
  "execution": {
    "deterministic": true,
    "externalRequests": 0,
    "maxExternalRequests": 0,
    "resultSnapshotPersisted": false,
    "fixedExampleIsIllustrativeSnapshot": false,
    "requiresPayment": true,
    "supportsMcpExecution": false
  },
  "releaseSnapshot": {
    "format": "static-release-reference-v1",
    "sourceVersion": "0.29.0",
    "sourceRegistrySha256": "a2b5ec09bf6c38b9d2879d746a4fded374f5928b445377b0270ef6aa8e6cac65",
    "generatedAt": "2026-10-06T15:38:00Z",
    "releaseAcceptance": "not-verified-by-generator",
    "runtimeReadiness": "not-evaluated",
    "livePaymentsVerified": false,
    "indexingVerified": false,
    "apiOrigin": null,
    "notice": "Build-time release reference. Runtime readiness, deployment, payment settlement and external indexing are not evaluated here. Prices are proposed; this file cannot authorize execution or payment."
  }
}