openapi: 3.1.0
info:
  title: ICS API
  version: 0.1.0-draft
  description: |
    Inventory Control (ICS).

    Contract notes:
    - API Gateway base path: `/ics`
    - Org-gated: supply `x-orgcode`.
    - Operational actions generally require logical facility context (`x-logical-guid`). Exceptions: transfer flows carry `source_logical_guid`/`dest_logical_guid` in the body (via `request_context`), and org-wide search/reporting endpoints are org-scoped only.
    - Stock lookups allow SKU-only requests without `x-logical-guid` for authorized members; results include `logical_guid`.
    - Channel context is required for reservations/allocations/commitments.
    - Request context is captured for auditability (org/facility/channel/roles/cost-centre).
    - Auth: either `x-session-guid` (user session) or `x-api-key` (org-bound service account).
      Headers are canonical; body `session_guid`/`api_key` accepted for compatibility on POST.
    - Roles: planning endpoints require `ics_planner`; operational writes require `ics_operator`;
      transfer submission requires `ics_transfer_approve`. Cost visibility uses `cost_view` or `finance_audit`.
servers:
  - url: https://api.g3nretailstack.com/ics
security:
  - sessionAuth: []
  - apiKeyAuth: []
components:
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: header
      name: x-session-guid
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  parameters:
    OrgHeader:
      in: header
      name: x-orgcode
      required: true
      schema: { type: string }
    LogicalHeader:
      in: header
      name: x-logical-guid
      required: true
      schema: { type: string }
    LogicalHeaderOptional:
      in: header
      name: x-logical-guid
      required: false
      schema: { type: string }
    ChannelHeader:
      in: header
      name: x-channel-code
      required: false
      schema: { type: string }
    CostCentreHeader:
      in: header
      name: x-cccode
      required: false
      schema: { type: string }
  schemas:
    BuildMeta:
      type: object
      properties:
        build_major: { type: string }
        build_minor: { type: string }
        build_id: { type: string }
      required: [build_major, build_minor, build_id]
    Stats:
      type: object
      properties:
        call: { type: string }
        service: { type: string, enum: [ics] }
        request_id: { type: string }
        timestamp_utc: { type: string, format: date-time }
        build: { $ref: '#/components/schemas/BuildMeta' }
        actor: { type: string }
        context_source:
          type: string
          enum: [session, api_key, operator, system]
        session_fingerprint:
          type: string
          description: Non-reversible SHA-256 fingerprint of the caller session (`session_guid`) for correlation (never an auth credential).
        api_key_fingerprint:
          type: string
          description: Non-reversible SHA-256 fingerprint of the caller `api_key` for correlation (never an auth credential).
        orgcode: { type: string }
        cccode: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        roles:
          type: array
          items: { type: string }
      required: [call, service, timestamp_utc, build]
    Error:
      type: object
      properties:
        error_code: { type: string }
        http_status: { type: integer }
        retryable: { type: boolean }
        request_id: { type: string }
        trace_id: { type: string }
        major: { type: string }
        minor: { type: string }
        message: { type: string }
        details: { type: object }
    Envelope:
      type: object
      properties:
        success: { type: boolean }
        data: { type: object }
        error: { $ref: '#/components/schemas/Error' }
        stats: { $ref: '#/components/schemas/Stats' }
    SourceRef:
      type: object
      properties:
        kind: { type: string }
        id: { type: string }
      required: [kind, id]
    PartyRef:
      type: object
      properties:
        kind: { type: string }
        id: { type: string }
      required: [kind, id]
    SourceRefs:
      type: array
      items: { $ref: '#/components/schemas/SourceRef' }
    IdempotencyKey:
      type: string
      description: Client-supplied idempotency key (ASCII <=128 chars). Scope is orgcode+route+idempotency_key; replay returns original response, mismatch returns 409 idempotency-conflict (retained 24h).
      maxLength: 128
    RequestContext:
      type: object
      properties:
        orgcode: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        cccode: { type: string }
        actor: { type: string }
        roles:
          type: array
          items: { type: string }
        context_source:
          type: string
          enum: [session, api_key, operator, system]
        session_fingerprint: { type: string }
        api_key_fingerprint: { type: string }
      required: [orgcode, actor, context_source]
      additionalProperties: false
    PolicyRefs:
      type: object
      properties:
        tax_policy_version: { type: string }
        pricing_policy_version: { type: string }
        promotion_policy_version: { type: string }
        discount_policy_version: { type: string }
        stacking_policy_version: { type: string }
        reservation_policy_version: { type: string }
        allocation_policy_version: { type: string }
        commit_policy_version: { type: string }
        replenishment_policy_version: { type: string }
        approval_policy_version: { type: string }
        tender_policy_version: { type: string }
        returns_policy_version: { type: string }
        loyalty_policy_version: { type: string }
        stored_value_policy_version: { type: string }
        earning_policy_version: { type: string }
        backorder_policy_version: { type: string }
        special_order_policy_version: { type: string }
        transfer_policy_version: { type: string }
        consignment_policy_version: { type: string }
        count_policy_version: { type: string }
        adjustment_policy_version: { type: string }
        po_policy_version: { type: string }
        matching_policy_version: { type: string }
        tolerance_policy_version: { type: string }
        receiving_policy_version: { type: string }
        qc_policy_version: { type: string }
        rtv_policy_version: { type: string }
        credit_policy_version: { type: string }
        shipping_policy_version: { type: string }
        export_policy_version: { type: string }
      additionalProperties: true
    Money:
      type: object
      properties:
        currency: { type: string }
        amount: { type: number }
      required: [currency, amount]
    LandedCost:
      type: object
      description: Landed cost breakdown per unit (duty + freight + insurance + other = total). All components are optional Money; total is always present.
      properties:
        duty: { $ref: '#/components/schemas/Money' }
        freight: { $ref: '#/components/schemas/Money' }
        insurance: { $ref: '#/components/schemas/Money' }
        other: { $ref: '#/components/schemas/Money' }
        total: { $ref: '#/components/schemas/Money' }
      required: [total]
    UomQuantity:
      type: object
      properties:
        qty: { type: number }
        uom: { type: string }
        uom_multiplier: { type: number }
      required: [qty, uom]
    StockBuckets:
      type: object
      properties:
        on_hand: { type: number }
        reserved: { type: number }
        allocated: { type: number }
        committed: { type: number }
        available: { type: number }
        in_transit: { type: number }
        quarantine: { type: number }
        damaged: { type: number }
        consignment: { type: number }
    StockPosition:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        logical_guid: { type: string }
        zone_code: { type: string }
        bin_code: { type: string }
        buckets: { $ref: '#/components/schemas/StockBuckets' }
        average_cost: { $ref: '#/components/schemas/Money' }
        landed_cost:
          $ref: '#/components/schemas/LandedCost'
          description: Optional landed cost breakdown. Present only when cost components were provided at receiving time.
        last_updated: { type: string, format: date-time }
        negative_stock_protection: { type: boolean }
        overcommit_allowed: { type: boolean }
        policy_updated_at: { type: string, format: date-time }
    StockPolicy:
      type: object
      properties:
        variant_id: { type: string }
        logical_guid: { type: string }
        negative_stock_protection: { type: boolean }
        overcommit_allowed: { type: boolean }
        policy_updated_at: { type: string, format: date-time }
        revision: { type: integer }
    StockPolicyDraft:
      type: object
      properties:
        variant_id: { type: string }
        logical_guid: { type: string }
        negative_stock_protection: { type: boolean }
        expected_revision: { type: integer }
    Bin:
      type: object
      properties:
        bin_id: { type: string }
        bin_code: { type: string }
        zone_code: { type: string }
        logical_guid: { type: string }
        status: { type: string }
        bin_type: { type: string }
        description: { type: string }
        capacity_qty: { $ref: '#/components/schemas/UomQuantity' }
        attributes: { type: object }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        revision: { type: integer }
    Zone:
      type: object
      properties:
        zone_id: { type: string }
        zone_code: { type: string }
        logical_guid: { type: string }
        status: { type: string }
        zone_type: { type: string }
        description: { type: string }
        attributes: { type: object }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        revision: { type: integer }
    ZoneDraft:
      type: object
      properties:
        zone_id: { type: string }
        zone_code: { type: string }
        logical_guid: { type: string }
        status: { type: string }
        zone_type: { type: string }
        description: { type: string }
        attributes: { type: object }
      required: [zone_code]
    ZoneCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        zone: { $ref: '#/components/schemas/ZoneDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [zone, reason, source_refs]
    ZoneGetRequest:
      type: object
      properties:
        zone_code: { type: string }
      required: [zone_code]
    ZoneListRequest:
      type: object
      properties:
        status: { type: string }
        limit: { type: integer }
        next_token: { type: string }
    ZoneStatusSetRequest:
      type: object
      properties:
        zone_code: { type: string }
        status: { type: string }
        expected_revision: { type: integer }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [zone_code, status, reason, source_refs]
    ZoneEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                zone: { $ref: '#/components/schemas/Zone' }
              required: [zone]
    ZoneListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                zones:
                  type: array
                  items: { $ref: '#/components/schemas/Zone' }
                next_token: { type: string }
              required: [zones]
    BinDraft:
      type: object
      properties:
        bin_id: { type: string }
        bin_code: { type: string }
        zone_code: { type: string }
        logical_guid: { type: string }
        status: { type: string }
        bin_type: { type: string }
        description: { type: string }
        capacity_qty: { $ref: '#/components/schemas/UomQuantity' }
        attributes: { type: object }
      required: [zone_code, bin_code]
    BinCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        bin: { $ref: '#/components/schemas/BinDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [bin, reason, source_refs]
    BinGetRequest:
      type: object
      properties:
        zone_code: { type: string }
        bin_code: { type: string }
      required: [zone_code, bin_code]
    BinListRequest:
      type: object
      properties:
        zone_code: { type: string }
        status: { type: string }
        limit: { type: integer }
        next_token: { type: string }
    BinStatusSetRequest:
      type: object
      properties:
        zone_code: { type: string }
        bin_code: { type: string }
        status: { type: string }
        expected_revision: { type: integer }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [zone_code, bin_code, status, reason, source_refs]
    BinEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                bin: { $ref: '#/components/schemas/Bin' }
              required: [bin]
    BinListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                bins:
                  type: array
                  items: { $ref: '#/components/schemas/Bin' }
                next_token: { type: object }
    ReplenishmentPolicyVersions:
      type: object
      properties:
        replenishment_policy_version: { type: string }
    ReplenishmentRule:
      type: object
      properties:
        rule_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        logical_guid: { type: string }
        pick_zone_code: { type: string }
        pick_bin_code: { type: string }
        overstock_zone_code: { type: string }
        overstock_bin_code: { type: string }
        min_qty: { $ref: '#/components/schemas/UomQuantity' }
        max_qty: { $ref: '#/components/schemas/UomQuantity' }
        status: { type: string }
        notes: { type: string }
        policy_versions: { $ref: '#/components/schemas/ReplenishmentPolicyVersions' }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        revision: { type: integer }
    ReplenishmentRuleDraft:
      type: object
      properties:
        rule_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        logical_guid: { type: string }
        pick_zone_code: { type: string }
        pick_bin_code: { type: string }
        overstock_zone_code: { type: string }
        overstock_bin_code: { type: string }
        min_qty: { $ref: '#/components/schemas/UomQuantity' }
        max_qty: { $ref: '#/components/schemas/UomQuantity' }
        status: { type: string }
        notes: { type: string }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
      required: [variant_id, pick_zone_code, pick_bin_code, min_qty, max_qty]
    ReplenishmentRuleSetRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        rule: { $ref: '#/components/schemas/ReplenishmentRuleDraft' }
        expected_revision: { type: integer }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [rule, reason, source_refs]
    ReplenishmentRuleGetRequest:
      type: object
      properties:
        rule_id: { type: string }
      required: [rule_id]
    ReplenishmentRuleListRequest:
      type: object
      properties:
        variant_id: { type: string }
        status: { type: string }
        pick_bin_code: { type: string }
        overstock_bin_code: { type: string }
        limit: { type: integer }
        next_token: { type: string }
    ReplenishmentRuleStatusSetRequest:
      type: object
      properties:
        rule_id: { type: string }
        status: { type: string }
        expected_revision: { type: integer }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [rule_id, status, reason, source_refs, expected_revision]
    ReplenishmentRuleEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                rule: { $ref: '#/components/schemas/ReplenishmentRule' }
              required: [rule]
    ReplenishmentRuleListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                rules:
                  type: array
                  items: { $ref: '#/components/schemas/ReplenishmentRule' }
                next_token: { type: string }
              required: [rules]
    StockGetRequest:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        include_bins: { type: boolean }
        limit: { type: integer }
        next_token: { type: string }
      required: []
    StockListRequest:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        zone_code: { type: string }
        bin_code: { type: string }
        limit: { type: integer }
        next_token: { type: string }
    StockPolicyGetRequest:
      type: object
      properties:
        variant_id: { type: string }
        logical_guid: { type: string }
      required: [variant_id]
    StockPolicySetRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        policy: { $ref: '#/components/schemas/StockPolicyDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [policy, reason, source_refs]
    StockEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                stock: { $ref: '#/components/schemas/StockPosition' }
                positions:
                  type: array
                  items: { $ref: '#/components/schemas/StockPosition' }
                next_token: { type: string }
    StockPolicyEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                policy: { $ref: '#/components/schemas/StockPolicy' }
              required: [policy]
    StockListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                positions:
                  type: array
                  items: { $ref: '#/components/schemas/StockPosition' }
                next_token: { type: string }
              required: [positions]
    ReservationLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        reason_code: { type: string }
        trace_mode: { type: string, enum: [fefo, fifo] }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
      required: [qty]
    Reservation:
      type: object
      properties:
        reservation_id: { type: string }
        status: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        order_ref: { type: string }
        expires_at:
          type: string
          format: date-time
          description: Defaulted when omitted (POS 5m, DTC/Shopify 15m, other/wholesale 60m).
        released_at: { type: string, format: date-time }
        expired_at: { type: string, format: date-time }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ReservationLine' }
        created_at: { type: string, format: date-time }
        revision: { type: integer }
    ReservationDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        order_ref: { type: string }
        expires_at:
          type: string
          format: date-time
          description: Defaulted when omitted (120m across channels unless overridden).
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ReservationLine' }
      required: [request_context, reason, source_refs]
    ReservationCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        reservation: { $ref: '#/components/schemas/ReservationDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [reservation, reason, source_refs]
    ReservationReleaseRequest:
      type: object
      properties:
        reservation_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [reservation_id, reason, source_refs]
    ReservationExpireRequest:
      type: object
      properties:
        reservation_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [reservation_id, reason, source_refs]
    ReservationEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                reservation: { $ref: '#/components/schemas/Reservation' }
              required: [reservation]
    AllocationLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        reason_code: { type: string }
        trace_mode: { type: string, enum: [fefo, fifo] }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
      required: [qty]
    Allocation:
      type: object
      properties:
        allocation_id: { type: string }
        status: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        order_ref: { type: string }
        expires_at: { type: string, format: date-time }
        released_at: { type: string, format: date-time }
        expired_at: { type: string, format: date-time }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/AllocationLine' }
        created_at: { type: string, format: date-time }
        revision: { type: integer }
    AllocationDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        order_ref: { type: string }
        expires_at: { type: string, format: date-time }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/AllocationLine' }
      required: [request_context, reason, source_refs]
    AllocationCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        allocation: { $ref: '#/components/schemas/AllocationDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [allocation, reason, source_refs]
    AllocationReleaseRequest:
      type: object
      properties:
        allocation_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [allocation_id, reason, source_refs]
    AllocationExpireRequest:
      type: object
      properties:
        allocation_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [allocation_id, reason, source_refs]
    AllocationEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                allocation: { $ref: '#/components/schemas/Allocation' }
              required: [allocation]
    CommitLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        trace_mode: { type: string, enum: [fefo, fifo] }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
      required: [qty]
    Commit:
      type: object
      properties:
        commit_id: { type: string }
        status: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        order_ref: { type: string }
        expires_at: { type: string, format: date-time }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/CommitLine' }
        created_at: { type: string, format: date-time }
        revision: { type: integer }
    CommitDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        order_ref: { type: string }
        expires_at: { type: string, format: date-time }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/CommitLine' }
      required: [request_context, reason, source_refs]
    CommitCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        commit: { $ref: '#/components/schemas/CommitDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [commit, reason, source_refs]
    CommitReleaseRequest:
      type: object
      properties:
        commit_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [commit_id, reason, source_refs]
    CommitEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                commit: { $ref: '#/components/schemas/Commit' }
              required: [commit]
    TransferLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        unit_cost: { $ref: '#/components/schemas/Money' }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
      required: [qty]
    TransferReceiptLine:
      allOf:
        - { $ref: '#/components/schemas/TransferLine' }
        - type: object
          required: [line_id, variant_id, qty]
    TransferShipmentException:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        qty_short: { type: number }
        uom: { type: string }
        reason_code: { type: string }
        notes: { type: string }
    TransferRequest:
      type: object
      properties:
        transfer_id: { type: string }
        status: { type: string }
        source_logical_guid: { type: string }
        dest_logical_guid: { type: string }
        shipment_count: { type: integer }
        received_shipment_count: { type: integer }
        exception_shipment_count: { type: integer }
        exception_line_count: { type: integer }
        exception_qty_total: { type: number }
        policy_versions:
          type: object
          properties:
            transfer_policy_version: { type: string }
            approval_policy_version: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/TransferLine' }
        requested_at: { type: string, format: date-time }
        submitted_at: { type: string, format: date-time }
        approved_at: { type: string, format: date-time }
        shipped_at: { type: string, format: date-time }
        received_at: { type: string, format: date-time }
        revision: { type: integer }
    TransferDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        source_logical_guid: { type: string }
        dest_logical_guid: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/TransferLine' }
        notes: { type: string }
      required: [request_context, reason, source_refs]
    TransferRequestCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        transfer: { $ref: '#/components/schemas/TransferDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [transfer, reason, source_refs]
    TransferRequestSubmitRequest:
      type: object
      properties:
        transfer_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [transfer_id, reason, source_refs]
    TransferRequestApproveRequest:
      type: object
      properties:
        transfer_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [transfer_id, reason, source_refs]
    TransferRequestGetRequest:
      type: object
      properties:
        transfer_id: { type: string }
      required: [transfer_id]
    TransferRequestListRequest:
      type: object
      properties:
        status: { type: string }
        source_logical_guid: { type: string }
        dest_logical_guid: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
    TransferReportRequest:
      type: object
      properties:
        status: { type: string }
        source_logical_guid: { type: string }
        dest_logical_guid: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        group_by_source: { type: boolean }
        group_by_dest: { type: boolean }
        group_by_pair: { type: boolean }
        bucket_by:
          type: string
          enum: [requested_at, shipped_at, received_at]
        bucket_unit:
          type: string
          enum: [day, week, month]
        bucket_limit: { type: integer }
        include_lead_time_buckets: { type: boolean }
        lead_time_bucket_ms:
          type: array
          items: { type: integer }
        limit: { type: integer }
        next_token: { type: string }
    TransferPairCount:
      type: object
      properties:
        source_logical_guid: { type: string }
        dest_logical_guid: { type: string }
        transfer_count: { type: integer }
      required: [transfer_count]
    TransferTimeBucket:
      type: object
      properties:
        bucket: { type: string }
        transfer_count: { type: integer }
      required: [bucket, transfer_count]
    LeadTimeBucket:
      type: object
      properties:
        min_ms: { type: integer }
        max_ms: { type: integer }
        transfer_count: { type: integer }
      required: [transfer_count]
    TransferEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                transfer: { $ref: '#/components/schemas/TransferRequest' }
              required: [transfer]
    TransferListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                transfers:
                  type: array
                  items: { $ref: '#/components/schemas/TransferRequest' }
                next_token: { type: string }
              required: [transfers]
    TransferReport:
      type: object
      properties:
        filters:
          type: object
          properties:
            status: { type: string }
            source_logical_guid: { type: string }
            dest_logical_guid: { type: string }
            created_from: { type: string, format: date-time }
            created_to: { type: string, format: date-time }
            bucket_by: { type: string }
            bucket_unit: { type: string }
            bucket_limit: { type: integer }
            include_lead_time_buckets: { type: boolean }
            lead_time_bucket_ms:
              type: array
              items: { type: integer }
        transfer_count: { type: integer }
        status_counts:
          type: object
          additionalProperties: { type: integer }
        source_counts:
          type: object
          additionalProperties: { type: integer }
        dest_counts:
          type: object
          additionalProperties: { type: integer }
        source_dest_counts:
          type: array
          items: { $ref: '#/components/schemas/TransferPairCount' }
        time_buckets:
          type: array
          items: { $ref: '#/components/schemas/TransferTimeBucket' }
        shipment_count_total: { type: integer }
        received_shipment_count_total: { type: integer }
        exception_shipment_count_total: { type: integer }
        exception_line_count_total: { type: integer }
        exception_qty_total: { type: number }
        open_transfer_count: { type: integer }
        avg_ship_lead_ms: { type: integer, nullable: true }
        avg_receive_lead_ms: { type: integer, nullable: true }
        ship_lead_sample_count: { type: integer }
        receive_lead_sample_count: { type: integer }
        ship_lead_buckets:
          type: array
          items: { $ref: '#/components/schemas/LeadTimeBucket' }
        receive_lead_buckets:
          type: array
          items: { $ref: '#/components/schemas/LeadTimeBucket' }
      required: [transfer_count]
    TransferReportEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                report: { $ref: '#/components/schemas/TransferReport' }
                next_token: { type: string }
              required: [report]
    TransferShipment:
      type: object
      properties:
        shipment_id: { type: string }
        transfer_id: { type: string }
        status: { type: string }
        shipped_at: { type: string, format: date-time }
        received_at: { type: string, format: date-time }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/TransferLine' }
        received_lines:
          type: array
          items: { $ref: '#/components/schemas/TransferReceiptLine' }
        exceptions:
          type: array
          items: { $ref: '#/components/schemas/TransferShipmentException' }
        exception_count: { type: integer }
        exception_qty_total: { type: number }
        exception_reason_codes:
          type: array
          items: { type: string }
    TransferShipmentSummary:
      type: object
      properties:
        shipment_id: { type: string }
        transfer_id: { type: string }
        status: { type: string }
        shipped_at: { type: string, format: date-time }
        received_at: { type: string, format: date-time }
        source_logical_guid: { type: string }
        dest_logical_guid: { type: string }
        line_count: { type: integer }
        total_qty: { type: number }
        uom: { type: string }
        exception_count: { type: integer }
        exception_qty_total: { type: number }
        exception_reason_codes:
          type: array
          items: { type: string }
      required: [shipment_id, transfer_id, status, shipped_at, source_logical_guid, dest_logical_guid]
    TransferShipmentRecordRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment: { $ref: '#/components/schemas/TransferShipment' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment, reason, source_refs]
    TransferShipmentGetRequest:
      type: object
      properties:
        transfer_id: { type: string }
        shipment_id: { type: string }
      required: [transfer_id, shipment_id]
    TransferShipmentListRequest:
      type: object
      properties:
        transfer_id: { type: string }
        status: { type: string }
        exceptions_only: { type: boolean }
        limit: { type: integer }
        next_token: { type: string }
    TransferReceiveRequest:
      type: object
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        received_lines:
          type: array
          items: { $ref: '#/components/schemas/TransferReceiptLine' }
        short_reason_code: { type: string }
        exception_notes: { type: string }
      required: [shipment_id, reason, source_refs]
    TransferShipmentEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                shipment: { $ref: '#/components/schemas/TransferShipment' }
              required: [shipment]
    TransferShipmentListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                shipments:
                  type: array
                  items: { $ref: '#/components/schemas/TransferShipmentSummary' }
                next_token: { type: string }
              required: [shipments]
    TransferSuggestion:
      type: object
      properties:
        suggestion_id: { type: string }
        source_logical_guid: { type: string }
        dest_logical_guid: { type: string }
        rationale: { type: string }
        recommended_qty: { $ref: '#/components/schemas/UomQuantity' }
        constraints:
          type: array
          items: { type: string }
    TransferSuggestRequest:
      type: object
      properties:
        source_logical_guid: { type: string }
        dest_logical_guid: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        as_of_utc: { type: string, format: date-time }
      required: []
    TransferSuggestEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                suggestions:
                  type: array
                  items: { $ref: '#/components/schemas/TransferSuggestion' }
              required: [suggestions]
    AllocationSuggestion:
      type: object
      properties:
        suggestion_id: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        rationale: { type: string }
        recommended_qty: { $ref: '#/components/schemas/UomQuantity' }
        constraints:
          type: array
          items: { type: string }
    AllocationSuggestRequest:
      type: object
      properties:
        logical_guid: { type: string }
        channel_code: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        as_of_utc: { type: string, format: date-time }
    AllocationSuggestEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                suggestions:
                  type: array
                  items: { $ref: '#/components/schemas/AllocationSuggestion' }
              required: [suggestions]
    CountLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        expected_qty: { $ref: '#/components/schemas/UomQuantity' }
        counted_qty: { $ref: '#/components/schemas/UomQuantity' }
        system_qty: { type: number }
        variance_qty: { type: number }
        variance_pct: { type: number }
        variance_exceeded: { type: boolean }
        reason_code: { type: string }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
    CountVarianceThreshold:
      type: object
      properties:
        abs_qty: { type: number }
        pct: { type: number }
    CountVarianceSummary:
      type: object
      properties:
        line_count: { type: integer }
        variance_line_count: { type: integer }
        variance_abs_total: { type: number }
        variance_abs_max: { type: number }
        variance_pct_max: { type: number }
        variance_qty_total: { type: number }
    CountPlan:
      type: object
      properties:
        plan_id: { type: string }
        caption: { type: string }
        logical_guid: { type: string }
        status: { type: string }
        blind: { type: boolean }
        require_approval: { type: boolean }
        variance_threshold: { $ref: '#/components/schemas/CountVarianceThreshold' }
        targets: { type: object }
        policy_versions:
          type: object
          properties:
            count_policy_version: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        revision: { type: integer }
    Count:
      type: object
      properties:
        count_id: { type: string }
        status: { type: string }
        count_type: { type: string, enum: [cycle, physical] }
        logical_guid: { type: string }
        plan_id: { type: string }
        count_plan: { $ref: '#/components/schemas/CountPlan' }
        blind: { type: boolean }
        require_approval: { type: boolean }
        variance_threshold: { $ref: '#/components/schemas/CountVarianceThreshold' }
        variance_summary: { $ref: '#/components/schemas/CountVarianceSummary' }
        policy_versions:
          type: object
          properties:
            count_policy_version: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/CountLine' }
        created_at: { type: string, format: date-time }
        submitted_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }
        approved_at: { type: string, format: date-time }
        approved_by: { type: string }
        rejected_at: { type: string, format: date-time }
        rejected_by: { type: string }
        submitted_by: { type: string }
        revision: { type: integer }
    CountCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        count: { $ref: '#/components/schemas/Count' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [count, reason, source_refs]
    CountSubmitRequest:
      type: object
      properties:
        count_id: { type: string }
        expected_revision: { type: integer }
        lines:
          type: array
          items: { $ref: '#/components/schemas/CountLine' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [count_id, reason, source_refs]
    CountApproveRequest:
      type: object
      properties:
        count_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [count_id, reason, source_refs]
    CountRejectRequest:
      type: object
      properties:
        count_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [count_id, reason, source_refs]
    CountPlanSetRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        plan: { $ref: '#/components/schemas/CountPlan' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [plan, reason, source_refs]
    CountPlanGetRequest:
      type: object
      properties:
        plan_id: { type: string }
      required: [plan_id]
    CountPlanListRequest:
      type: object
      properties:
        status: { type: string }
        limit: { type: integer }
        next_token: { type: object }
    CountPlanStatusSetRequest:
      type: object
      properties:
        plan_id: { type: string }
        status: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [plan_id, status, reason, source_refs]
    CountEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                count: { $ref: '#/components/schemas/Count' }
              required: [count]
    CountPlanEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                plan: { $ref: '#/components/schemas/CountPlan' }
              required: [plan]
    CountPlanListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                plans:
                  type: array
                  items: { $ref: '#/components/schemas/CountPlan' }
                next_token: { type: object }
              required: [plans]
    ReceiptLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        unit_cost: { $ref: '#/components/schemas/Money' }
        duty_cost:
          $ref: '#/components/schemas/Money'
          description: Optional duty/tariff cost per unit for landed cost calculation.
        freight_cost:
          $ref: '#/components/schemas/Money'
          description: Optional freight cost per unit for landed cost calculation.
        insurance_cost:
          $ref: '#/components/schemas/Money'
          description: Optional insurance cost per unit for landed cost calculation.
        other_cost:
          $ref: '#/components/schemas/Money'
          description: Optional other landed cost per unit (brokerage, handling, etc.).
        reason_code: { type: string }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        qc_passed_qty: { $ref: '#/components/schemas/UomQuantity' }
        qc_failed_qty: { $ref: '#/components/schemas/UomQuantity' }
        qc_status: { type: string, enum: [passed, failed, partial] }
        qc_reason_code: { type: string }
      required: [qty]
    Receipt:
      type: object
      properties:
        receipt_id: { type: string }
        logical_guid: { type: string }
        status: { type: string }
        qc_status: { type: string }
        qc_required: { type: boolean }
        receiving_zone_code: { type: string }
        receiving_bin_code: { type: string }
        qc_zone_code: { type: string }
        qc_bin_code: { type: string }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ReceiptLine' }
        policy_versions:
          type: object
          properties:
            receiving_policy_version: { type: string }
            qc_policy_version: { type: string }
        received_at: { type: string, format: date-time }
        qc_completed_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        revision: { type: integer }
    ReceiveRecordRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        receipt: { $ref: '#/components/schemas/Receipt' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [receipt, reason, source_refs]
    ReceiveGetRequest:
      type: object
      properties:
        receipt_id: { type: string }
      required: [receipt_id]
    ReceiveListRequest:
      type: object
      properties:
        status: { type: string }
        limit: { type: integer }
        next_token: { type: object }
    ReceiveEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                receipt: { $ref: '#/components/schemas/Receipt' }
              required: [receipt]
    ReceiveListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                receipts:
                  type: array
                  items: { $ref: '#/components/schemas/Receipt' }
                next_token: { type: object }
              required: [receipts]
    QcLine:
      type: object
      properties:
        line_id: { type: string }
        passed_qty: { $ref: '#/components/schemas/UomQuantity' }
        failed_qty: { $ref: '#/components/schemas/UomQuantity' }
        reason_code: { type: string }
      required: [line_id]
    QcRequest:
      type: object
      properties:
        receipt_id: { type: string }
        qc_zone_code: { type: string }
        qc_bin_code: { type: string }
        lines:
          type: array
          items: { $ref: '#/components/schemas/QcLine' }
      required: [receipt_id, lines]
    QcCompleteRequest:
      type: object
      properties:
        qc: { $ref: '#/components/schemas/QcRequest' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [qc, reason, source_refs]
    Adjustment:
      type: object
      properties:
        adjustment_id: { type: string }
        status: { type: string }
        logical_guid: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        unit_cost: { $ref: '#/components/schemas/Money' }
        policy_versions:
          type: object
          properties:
            adjustment_policy_version: { type: string }
          required: [adjustment_policy_version]
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        delta_qty: { $ref: '#/components/schemas/UomQuantity' }
        from_bucket:
          type: string
          description: "Stock bucket to deduct from. Valid: available, quarantine, damaged, consignment, reserved, committed, in_transit. Defaults to available."
          enum: [available, quarantine, damaged, consignment, reserved, committed, in_transit]
        reason_code: { type: string }
        created_at: { type: string, format: date-time }
        revision: { type: integer }
      required: [policy_versions]
    AdjustmentCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        adjustment: { $ref: '#/components/schemas/Adjustment' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [adjustment, reason, source_refs]
    AdjustmentEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                adjustment: { $ref: '#/components/schemas/Adjustment' }
              required: [adjustment]
    StockTransition:
      type: object
      properties:
        transition_id: { type: string }
        logical_guid: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        from_bucket: { type: string, enum: [available, quarantine, damaged] }
        to_bucket: { type: string, enum: [available, quarantine, damaged] }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        policy_versions:
          type: object
          properties:
            transition_policy_version: { type: string }
          required: [transition_policy_version]
        reason_code: { type: string }
        occurred_at: { type: string, format: date-time }
      required: [transition_id, variant_id, logical_guid, qty, from_bucket, to_bucket, policy_versions]
    StockTransitionRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        transition: { $ref: '#/components/schemas/StockTransition' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [transition, reason, source_refs]
    StockTransitionEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                transition: { $ref: '#/components/schemas/StockTransition' }
              required: [transition]
    ConsignmentLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        reason_code: { type: string }
      required: [variant_id, qty]
    ConsignmentRecord:
      type: object
      properties:
        consignment_id: { type: string }
        consignment_type: { type: string, enum: [receive, consume, settle] }
        status: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        order_ref: { type: string }
        owner_ref: { $ref: '#/components/schemas/PartyRef' }
        possessor_ref: { $ref: '#/components/schemas/PartyRef' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ConsignmentLine' }
        amount: { $ref: '#/components/schemas/Money' }
        created_at: { type: string, format: date-time }
        settled_at: { type: string, format: date-time }
        revision: { type: integer }
    ConsignmentReceiveDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        consignment_id: { type: string }
        logical_guid: { type: string }
        owner_ref: { $ref: '#/components/schemas/PartyRef' }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ConsignmentLine' }
      required: [request_context, reason, source_refs, owner_ref, lines]
    ConsignmentConsumeDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        consignment_id: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        order_ref: { type: string }
        owner_ref: { $ref: '#/components/schemas/PartyRef' }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ConsignmentLine' }
      required: [request_context, reason, source_refs, owner_ref, lines, channel_code]
    ConsignmentSettlementDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        consignment_id: { type: string }
        logical_guid: { type: string }
        owner_ref: { $ref: '#/components/schemas/PartyRef' }
        amount: { $ref: '#/components/schemas/Money' }
        settled_at: { type: string, format: date-time }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ConsignmentLine' }
      required: [request_context, reason, source_refs, owner_ref, amount, lines]
    ConsignmentReceiveRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        consignment: { $ref: '#/components/schemas/ConsignmentReceiveDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [consignment, reason, source_refs]
    ConsignmentConsumeRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        consignment: { $ref: '#/components/schemas/ConsignmentConsumeDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [consignment, reason, source_refs]
    ConsignmentSettlementRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        settlement: { $ref: '#/components/schemas/ConsignmentSettlementDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [settlement, reason, source_refs]
    ConsignmentEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                consignment: { $ref: '#/components/schemas/ConsignmentRecord' }
              required: [consignment]
    StockCardEntry:
      type: object
      properties:
        entry_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        logical_guid: { type: string }
        action: { type: string }
        delta_qty: { $ref: '#/components/schemas/UomQuantity' }
        qty_moved: { type: number }
        from_bucket: { type: string, enum: [available, quarantine, damaged] }
        to_bucket: { type: string, enum: [available, quarantine, damaged] }
        cost_delta: { $ref: '#/components/schemas/Money' }
        reason_code: { type: string }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        owner_ref: { $ref: '#/components/schemas/PartyRef' }
        possessor_ref: { $ref: '#/components/schemas/PartyRef' }
        from_zone_code: { type: string }
        from_bin_code: { type: string }
        to_zone_code: { type: string }
        to_bin_code: { type: string }
        actor_ref: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        occurred_at: { type: string, format: date-time }
    StockCardEntryEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                entry: { $ref: '#/components/schemas/StockCardEntry' }
              required: [entry]
    PutawayRecord:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        from_zone_code: { type: string }
        from_bin_code: { type: string }
        to_zone_code: { type: string }
        to_bin_code: { type: string }
        logical_guid: { type: string }
        reason_code: { type: string }
      required: [variant_id, qty, to_zone_code, to_bin_code]
    PutawayRecordRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        putaway: { $ref: '#/components/schemas/PutawayRecord' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [putaway, reason, source_refs]
    PickRecord:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        from_zone_code: { type: string }
        from_bin_code: { type: string }
        to_zone_code: { type: string }
        to_bin_code: { type: string }
        logical_guid: { type: string }
        reason_code: { type: string }
      required: [variant_id, qty, from_zone_code, from_bin_code]
    PickRecordRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        pick: { $ref: '#/components/schemas/PickRecord' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [pick, reason, source_refs]
    PackRecord:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        from_zone_code: { type: string }
        from_bin_code: { type: string }
        to_zone_code: { type: string }
        to_bin_code: { type: string }
        logical_guid: { type: string }
        reason_code: { type: string }
      required: [variant_id, qty, from_zone_code, from_bin_code, to_zone_code, to_bin_code]
    PackRecordRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        pack: { $ref: '#/components/schemas/PackRecord' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [pack, reason, source_refs]
    ShipRecord:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        from_zone_code: { type: string }
        from_bin_code: { type: string }
        to_zone_code: { type: string }
        to_bin_code: { type: string }
        logical_guid: { type: string }
        reason_code: { type: string }
      required: [variant_id, qty, from_zone_code, from_bin_code, to_zone_code, to_bin_code]
    ShipRecordRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        ship: { $ref: '#/components/schemas/ShipRecord' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [ship, reason, source_refs]
    ReplenishmentRecord:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        lot_id: { type: string }
        expiry_at: { type: string, format: date-time }
        serials:
          type: array
          items: { type: string }
        rule_id: { type: string }
        from_zone_code: { type: string }
        from_bin_code: { type: string }
        to_zone_code: { type: string }
        to_bin_code: { type: string }
        logical_guid: { type: string }
        reason_code: { type: string }
      required: [variant_id, qty, from_zone_code, from_bin_code, to_zone_code, to_bin_code]
    ReplenishmentRecordRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        replenishment: { $ref: '#/components/schemas/ReplenishmentRecord' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [replenishment, reason, source_refs]
    ReplenishmentSuggestion:
      type: object
      properties:
        suggestion_id: { type: string }
        rule_id: { type: string }
        logical_guid: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        pick_zone_code: { type: string }
        pick_bin_code: { type: string }
        overstock_zone_code: { type: string }
        overstock_bin_code: { type: string }
        current_qty: { $ref: '#/components/schemas/UomQuantity' }
        min_qty: { $ref: '#/components/schemas/UomQuantity' }
        max_qty: { $ref: '#/components/schemas/UomQuantity' }
        recommended_qty: { $ref: '#/components/schemas/UomQuantity' }
        rationale: { type: string }
        constraints:
          type: array
          items: { type: string }
    ReplenishmentSuggestRequest:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        status: { type: string }
        pick_bin_code: { type: string }
        overstock_bin_code: { type: string }
        as_of_utc: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
    ReplenishmentSuggestEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                suggestions:
                  type: array
                  items: { $ref: '#/components/schemas/ReplenishmentSuggestion' }
                next_token: { type: string }
              required: [suggestions]
    StockCardListRequest:
      type: object
      properties:
        variant_id: { type: string }
        sku: { type: string }
        logical_guid: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
    StockCardEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                entries:
                  type: array
                  items: { $ref: '#/components/schemas/StockCardEntry' }
                next_token: { type: string }
              required: [entries]
    CommentAttachment:
      type: object
      properties:
        mrs_guid: { type: string }
        caption: { type: string }
        filename: { type: string }
        content_type: { type: string }
        size_bytes: { type: integer, minimum: 0 }
      required: [mrs_guid]
    Comment:
      type: object
      properties:
        comment_id: { type: string }
        target_type: { type: string }
        target_id: { type: string }
        parent_comment_id: { type: string }
        caption: { type: string }
        body: { type: string }
        attachments:
          type: array
          items: { $ref: '#/components/schemas/CommentAttachment' }
        total_size_bytes: { type: integer }
        hashtags:
          type: array
          items: { type: string }
        mentions_users:
          type: array
          items: { type: string }
        mentions_teams:
          type: array
          items: { type: string }
        status:
          type: string
          enum: [current, archived, doomed, all]
          default: current
          description: Default current; use all to include archived/doomed.
        current_revision: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        author_guid: { type: string }
      required: [comment_id, target_type, target_id, status, current_revision, created_at]
    CommentAddRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        target_type: { type: string }
        target_id: { type: string }
        parent_comment_id: { type: string }
        caption: { type: string }
        body: { type: string }
        attachments:
          type: array
          items: { $ref: '#/components/schemas/CommentAttachment' }
        hashtags:
          type: array
          items: { type: string }
        mentions_users:
          type: array
          items: { type: string }
        mentions_teams:
          type: array
          items: { type: string }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
      required: [target_type, target_id]
    CommentGetRequest:
      type: object
      properties:
        comment_id: { type: string }
        target_type: { type: string }
        target_id: { type: string }
      required: [comment_id, target_type, target_id]
    CommentListRequest:
      type: object
      properties:
        target_type: { type: string }
        target_id: { type: string }
        user_guid: { type: string }
        org_wide: { type: boolean }
        status: { type: string, enum: [current, archived, doomed] }
        hashtag: { type: string }
        created_after: { type: string, format: date-time }
        created_before: { type: string, format: date-time }
        limit: { type: integer, minimum: 1, maximum: 100 }
        next_token: { type: string }
      description: Requires target_type+target_id, user_guid, or org_wide=true.
    CommentReviseRequest:
      type: object
      properties:
        comment_id: { type: string }
        target_type: { type: string }
        target_id: { type: string }
        caption: { type: string }
        body: { type: string }
        attachments:
          type: array
          items: { $ref: '#/components/schemas/CommentAttachment' }
        hashtags:
          type: array
          items: { type: string }
        mentions_users:
          type: array
          items: { type: string }
        mentions_teams:
          type: array
          items: { type: string }
        expected_revision: { type: integer }
      required: [comment_id, target_type, target_id]
    CommentStatusRequest:
      type: object
      properties:
        comment_id: { type: string }
        target_type: { type: string }
        target_id: { type: string }
        status: { type: string, enum: [current, archived, doomed] }
      required: [comment_id, target_type, target_id, status]
    CommentReportRequest:
      type: object
      properties:
        limit: { type: integer, minimum: 1, maximum: 100 }
    CommentEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                comment: { $ref: '#/components/schemas/Comment' }
              required: [comment]
    CommentListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items: { $ref: '#/components/schemas/Comment' }
                next_token: { type: string }
              required: [items]
    CommentReportEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      comment_id: { type: string }
                      target_type: { type: string }
                      target_id: { type: string }
                      total_size_bytes: { type: integer }
                      created_at: { type: string, format: date-time }
                    required: [comment_id, target_type, target_id]
              required: [items]
    InboxNotification:
      type: object
      properties:
        notification_id: { type: string }
        team_guid: { type: string }
        status:
          type: string
          enum: [inbox, archived, all]
          default: inbox
          description: Default inbox; use all to include archived.
        state: { type: string, enum: [pending, completed, deferred] }
        priority: { type: string, enum: [low, medium, high, show_stopper] }
        act_by: { type: string, format: date-time }
        record_type: { type: string }
        record_id: { type: string }
        title: { type: string }
        body: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        created_by: { type: string }
      required: [notification_id, team_guid, status, state, priority, title]
    InboxCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        team_guid: { type: string }
        record_type: { type: string }
        record_id: { type: string }
        title: { type: string }
        body: { type: string }
        priority: { type: string, enum: [low, medium, high, show_stopper] }
        act_by: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
      required: [team_guid, title]
    InboxGetRequest:
      type: object
      properties:
        notification_id: { type: string }
      required: [notification_id]
    InboxListRequest:
      type: object
      properties:
        team_guid: { type: string }
        org_wide: { type: boolean }
        status: { type: string, enum: [inbox, archived] }
        state: { type: string, enum: [pending, completed, deferred] }
        limit: { type: integer, minimum: 1, maximum: 100 }
        next_token: { type: string }
      description: Requires team_guid unless org_wide=true (owner-only).
    InboxStatusRequest:
      type: object
      properties:
        notification_id: { type: string }
        status: { type: string, enum: [inbox, archived] }
      required: [notification_id, status]
    InboxStateRequest:
      type: object
      properties:
        notification_id: { type: string }
        state: { type: string, enum: [pending, completed, deferred] }
      required: [notification_id, state]
    CommentSearchRequest:
      type: object
      properties:
        q: { type: string }
        services:
          type: array
          items: { type: string }
        target_type: { type: string }
        target_id: { type: string }
        user_guid: { type: string }
        status: { type: string, enum: [current, archived, doomed] }
        hashtag: { type: string }
        created_after: { type: string, format: date-time }
        created_before: { type: string, format: date-time }
        limit: { type: integer, minimum: 1, maximum: 256 }
        next_token: { type: string }
    CommentSearchItem:
      type: object
      properties:
        service: { type: string }
        comment_id: { type: string }
        target_type: { type: string }
        target_id: { type: string }
        status: { type: string }
        current_revision: { type: integer }
        author_guid: { type: string }
        hashtags:
          type: array
          items: { type: string }
        mentions_users:
          type: array
          items: { type: string }
        mentions_teams:
          type: array
          items: { type: string }
        caption: { type: string }
        body: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
      required: [service, comment_id, target_type, target_id]
    CommentSearchEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items: { $ref: '#/components/schemas/CommentSearchItem' }
                next_token: { type: string }
              required: [items]
    InboxSearchRequest:
      type: object
      properties:
        q: { type: string }
        services:
          type: array
          items: { type: string }
        team_guid: { type: string }
        org_wide: { type: boolean }
        status: { type: string, enum: [inbox, archived] }
        state: { type: string, enum: [pending, completed, deferred] }
        record_type: { type: string }
        record_id: { type: string }
        priority: { type: string, enum: [low, medium, high, show_stopper] }
        created_after: { type: string, format: date-time }
        created_before: { type: string, format: date-time }
        limit: { type: integer, minimum: 1, maximum: 256 }
        next_token: { type: string }
      description: Requires team_guid unless org_wide=true (owner-only).
    InboxSearchItem:
      type: object
      properties:
        service: { type: string }
        notification_id: { type: string }
        team_guid: { type: string }
        status: { type: string }
        state: { type: string }
        priority: { type: string }
        act_by: { type: string, format: date-time }
        record_type: { type: string }
        record_id: { type: string }
        title: { type: string }
        body: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
      required: [service, notification_id, team_guid]
    InboxSearchEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items: { $ref: '#/components/schemas/InboxSearchItem' }
                next_token: { type: string }
              required: [items]
    InboxEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                notification: { $ref: '#/components/schemas/InboxNotification' }
              required: [notification]
    InboxListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items: { $ref: '#/components/schemas/InboxNotification' }
                next_token: { type: string }
              required: [items]
paths:
  /stat:
    get:
      summary: Health check
      description: |
        Health check. Tenant routes require x-orgcode; /stat health checks do not. Org-scoped reads may
        return 404 for non-associated callers (anti-enumeration). Route class Tier A (p95 500ms).
      x-route-class: Tier A
      x-qps-target: 5
      x-concurrency-target: 2
      x-latency-p95-ms: 500
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          service: { type: string }
                          status: { type: string }
  /stock/get:
    post:
      summary: Get stock position (draft)
      description: |
        When `sku` is provided without `logical_guid`, returns a list of matching positions across authorized logical facilities.
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2500
      x-concurrency-target: 3000
      x-latency-p95-ms: 150
      x-latency-p99-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeaderOptional' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StockGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockEnvelope' }
  /stock/policy/get:
    post:
      summary: Get stock policy (draft)
      description: |
        Get stock policy (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier C (p95 150ms, p99 400ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 3000
      x-latency-p95-ms: 150
      x-latency-p99-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StockPolicyGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockPolicyEnvelope' }
  /stock/policy/set:
    post:
      summary: Set stock policy (draft)
      description: |
        Set stock policy (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 250ms, p99 500ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1500
      x-latency-p95-ms: 250
      x-latency-p99-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StockPolicySetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockPolicyEnvelope' }
  /stock/list:
    post:
      summary: List stock positions (draft)
      description: |
        When `sku` is provided without `logical_guid`, returns matching positions across authorized logical facilities.
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 3000
      x-concurrency-target: 4000
      x-latency-p95-ms: 150
      x-latency-p99-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeaderOptional' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StockListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockListEnvelope' }
  /stock/transition:
    post:
      summary: Transition stock between buckets (draft)
      description: |
        Transition stock between buckets (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1500
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StockTransitionRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockTransitionEnvelope' }
  /bin/create:
    post:
      summary: Create bin (draft)
      description: |
        Create bin (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BinCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BinEnvelope' }
  /bin/get:
    post:
      summary: Get bin (draft)
      description: |
        Get bin (draft). Auth is via headers; org identity uses x-orgcode or body placement as documented.
        Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route class Tier B
        (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BinGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BinEnvelope' }
  /bin/list:
    post:
      summary: List bins (draft)
      description: |
        List bins (draft). Auth is via headers; org identity uses x-orgcode or body placement as documented.
        Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BinListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BinListEnvelope' }
  /bin/status/set:
    post:
      summary: Set bin status (draft)
      description: |
        Set bin status (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier B (p95 350ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 350
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BinStatusSetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BinEnvelope' }
  /replenishment/rule/set:
    post:
      summary: Set replenishment rule (draft)
      description: |
        Set replenishment rule (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. If this updates a revisioned record, expected_revision is required (428 if missing;
        409 on mismatch). Route class Tier B (p95 350ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 350
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReplenishmentRuleSetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReplenishmentRuleEnvelope' }
  /replenishment/rule/get:
    post:
      summary: Get replenishment rule (draft)
      description: |
        Get replenishment rule (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier C (p95 250ms, p99 600ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 250
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReplenishmentRuleGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReplenishmentRuleEnvelope' }
  /replenishment/rule/list:
    post:
      summary: List replenishment rules (draft)
      description: |
        List replenishment rules (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier C (p95
        300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReplenishmentRuleListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReplenishmentRuleListEnvelope' }
  /replenishment/rule/status/set:
    post:
      summary: Set replenishment rule status (draft)
      description: |
        Set replenishment rule status (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. If this updates a revisioned record, expected_revision is required (428 if
        missing; 409 on mismatch). Route class Tier B (p95 350ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 350
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReplenishmentRuleStatusSetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReplenishmentRuleEnvelope' }
  /replenishment/record:
    post:
      summary: Record replenishment movement (draft)
      description: |
        Record replenishment movement (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. If this updates a revisioned record, expected_revision is required (428 if
        missing; 409 on mismatch). Route class Tier B (p95 350ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 350
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReplenishmentRecordRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockCardEntryEnvelope' }
  /replenishment/suggest:
    post:
      summary: Suggest replenishment quantities (draft)
      description: |
        Suggest replenishment quantities (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReplenishmentSuggestRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReplenishmentSuggestEnvelope' }
  /zone/create:
    post:
      summary: Create zone (draft)
      description: |
        Create zone (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ZoneCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ZoneEnvelope' }
  /zone/get:
    post:
      summary: Get zone (draft)
      description: |
        Get zone (draft). Auth is via headers; org identity uses x-orgcode or body placement as documented.
        Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route class Tier C
        (p95 250ms, p99 600ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 250
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ZoneGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ZoneEnvelope' }
  /zone/list:
    post:
      summary: List zones (draft)
      description: |
        List zones (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier C (p95 250ms,
        p99 600ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 250
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ZoneListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ZoneListEnvelope' }
  /zone/status/set:
    post:
      summary: Set zone status (draft)
      description: |
        Set zone status (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier B (p95 350ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 350
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ZoneStatusSetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ZoneEnvelope' }
  /putaway/record:
    post:
      summary: Record putaway movement (draft)
      description: |
        Record putaway movement (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. If this updates a revisioned record, expected_revision is required (428 if missing;
        409 on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PutawayRecordRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockCardEntryEnvelope' }
  /pick/record:
    post:
      summary: Record pick movement (draft)
      description: |
        Record pick movement (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PickRecordRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockCardEntryEnvelope' }
  /pack/record:
    post:
      summary: Record pack movement (draft)
      description: |
        Record pack movement (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PackRecordRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockCardEntryEnvelope' }
  /ship/record:
    post:
      summary: Record ship movement (draft)
      description: |
        Record ship movement (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipRecordRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockCardEntryEnvelope' }
  /receive/record:
    post:
      summary: Record receipt (draft)
      description: |
        Record receipt (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReceiveRecordRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReceiveEnvelope' }
  /receive/get:
    post:
      summary: Get receipt (draft)
      description: |
        Get receipt (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier C (p95 250ms, p99 600ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 500
      x-concurrency-target: 800
      x-latency-p95-ms: 250
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReceiveGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReceiveEnvelope' }
  /receive/list:
    post:
      summary: List receipts (draft)
      description: |
        List receipts (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier C (p95 350ms,
        p99 800ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 500
      x-concurrency-target: 800
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReceiveListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReceiveListEnvelope' }
  /qc/complete:
    post:
      summary: Complete QC for a receipt (draft)
      description: |
        Complete QC for a receipt (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 350ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1500
      x-latency-p95-ms: 350
      x-latency-p99-ms: 700
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QcCompleteRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReceiveEnvelope' }
  /reservation/create:
    post:
      summary: Create reservation (draft)
      description: |
        Create reservation (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 700
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReservationCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReservationEnvelope' }
  /reservation/release:
    post:
      summary: Release reservation (draft)
      description: |
        Release reservation (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReservationReleaseRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReservationEnvelope' }
  /reservation/expire:
    post:
      summary: Expire reservation (draft)
      description: |
        Expire reservation (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReservationExpireRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReservationEnvelope' }
  /allocation/create:
    post:
      summary: Create allocation (draft)
      description: |
        Create allocation (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 700
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AllocationCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AllocationEnvelope' }
  /allocation/release:
    post:
      summary: Release allocation (draft)
      description: |
        Release allocation (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AllocationReleaseRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AllocationEnvelope' }
  /allocation/expire:
    post:
      summary: Expire allocation (draft)
      description: |
        Expire allocation (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AllocationExpireRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AllocationEnvelope' }
  /commit/create:
    post:
      summary: Create commit (draft)
      description: |
        Create commit (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommitCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommitEnvelope' }
  /commit/create-direct:
    post:
      summary: Direct commit from available stock (draft)
      description: |
        Direct commit — atomically moves stock from available to committed in a single step, bypassing
        reservation and allocation phases. Designed for in-store POS fast checkout where intermediate
        promise states add no business value. Condition: available >= qty. Stores commit_mode: 'direct'
        on the commit record. Route class Tier D (p95 200ms, p99 400ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1500
      x-concurrency-target: 2500
      x-latency-p95-ms: 200
      x-latency-p99-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommitCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommitEnvelope' }
  /commit/release:
    post:
      summary: Release commit (draft)
      description: |
        Release commit (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommitReleaseRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommitEnvelope' }
  /transfer/request/create:
    post:
      summary: Create transfer request (draft)
      description: |
        Create transfer request (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. If this updates a revisioned record, expected_revision is required (428 if missing;
        409 on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferRequestCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferEnvelope' }
  /transfer/request/submit:
    post:
      summary: Submit transfer request (draft)
      description: |
        Submit transfer request (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. If this updates a revisioned record, expected_revision is required (428 if missing;
        409 on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferRequestSubmitRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferEnvelope' }
  /transfer/request/approve:
    post:
      summary: Approve transfer request (draft)
      description: |
        Approve transfer request (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. If this updates a revisioned record, expected_revision is required (428 if missing;
        409 on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferRequestApproveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferEnvelope' }
  /transfer/request/get:
    post:
      summary: Get transfer request (draft)
      description: |
        Get transfer request (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferRequestGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferEnvelope' }
  /transfer/request/list:
    post:
      summary: List transfer requests (draft)
      description: |
        List transfer requests (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferRequestListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferListEnvelope' }
  /transfer/report:
    post:
      summary: Transfer analytics report (draft)
      description: |
        Transfer analytics report (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier B (p95 500ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferReportRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferReportEnvelope' }
  /transfer/shipment/record:
    post:
      summary: Record transfer shipment (draft)
      description: |
        Record transfer shipment (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. If this updates a revisioned record, expected_revision is required (428 if missing;
        409 on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferShipmentRecordRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferShipmentEnvelope' }
  /transfer/shipment/receive:
    post:
      summary: Receive transfer shipment (draft)
      description: |
        Receive transfer shipment (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 400
      x-concurrency-target: 600
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferReceiveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferShipmentEnvelope' }
  /transfer/shipment/get:
    post:
      summary: Get transfer shipment (draft)
      description: |
        Get transfer shipment (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferShipmentGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferShipmentEnvelope' }
  /transfer/shipment/list:
    post:
      summary: List transfer shipments (draft)
      description: |
        List transfer shipments (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferShipmentListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferShipmentListEnvelope' }
  /transfer/suggest:
    post:
      summary: Suggest transfer quantities (draft)
      description: |
        Suggest transfer quantities (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferSuggestRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransferSuggestEnvelope' }
  /allocation/suggest:
    post:
      summary: Suggest allocation quantities (draft)
      description: |
        Suggest allocation quantities (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AllocationSuggestRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AllocationSuggestEnvelope' }
  /count/create:
    post:
      summary: Create count (draft)
      description: |
        Create count (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CountCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
  /count/plan/set:
    post:
      summary: Create or update count plan (draft)
      description: |
        Create or update count plan (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. If this updates a revisioned record, expected_revision is required (428 if
        missing; 409 on mismatch). Route class Tier C (p95 350ms, p99 800ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 300
      x-concurrency-target: 600
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CountPlanSetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountPlanEnvelope' }
  /count/plan/get:
    post:
      summary: Get count plan (draft)
      description: |
        Get count plan (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier C (p95 250ms, p99 600ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 500
      x-concurrency-target: 800
      x-latency-p95-ms: 250
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CountPlanGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountPlanEnvelope' }
  /count/plan/list:
    post:
      summary: List count plans (draft)
      description: |
        List count plans (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier C (p95 350ms,
        p99 800ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 500
      x-concurrency-target: 800
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CountPlanListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountPlanListEnvelope' }
  /count/plan/status/set:
    post:
      summary: Set count plan status (draft)
      description: |
        Set count plan status (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier C (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 300
      x-concurrency-target: 600
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CountPlanStatusSetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountPlanEnvelope' }
  /count/submit:
    post:
      summary: Submit count results (draft)
      description: |
        Submit count results (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CountSubmitRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
  /count/approve:
    post:
      summary: Approve count results (draft)
      description: |
        Approve count results (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 400ms, p99 900ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 300
      x-concurrency-target: 600
      x-latency-p95-ms: 400
      x-latency-p99-ms: 900
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CountApproveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
  /count/reject:
    post:
      summary: Reject count results (draft)
      description: |
        Reject count results (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 800ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 300
      x-concurrency-target: 600
      x-latency-p95-ms: 300
      x-latency-p99-ms: 800
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CountRejectRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
  /adjustment/create:
    post:
      summary: Create manual adjustment (draft)
      description: |
        Create manual adjustment (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. If this updates a revisioned record, expected_revision is required (428 if missing;
        409 on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AdjustmentCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdjustmentEnvelope' }
  /consignment/receive:
    post:
      summary: Receive consignment stock (draft)
      description: |
        Receive consignment stock (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 400ms, p99 800ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1500
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ConsignmentReceiveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ConsignmentEnvelope' }
  /consignment/consume:
    post:
      summary: Consume consignment stock (draft)
      description: |
        Consume consignment stock (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier C (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 1200
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' }, { $ref: '#/components/parameters/ChannelHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ConsignmentConsumeRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ConsignmentEnvelope' }
  /consignment/settle:
    post:
      summary: Settle consignment usage (draft)
      description: |
        Settle consignment usage (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. If this updates a revisioned record, expected_revision is required (428 if missing;
        409 on mismatch). Route class Tier D (p95 400ms, p99 800ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 1200
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ConsignmentSettlementRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ConsignmentEnvelope' }
  /stock/card/list:
    post:
      summary: List stock card entries (draft)
      description: |
        List stock card entries (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StockCardListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StockCardEnvelope' }
  /comment:
    post:
      summary: Add comment (draft)
      description: |
        Add comment (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentAddRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentEnvelope' }
  /comment/get:
    post:
      summary: Get comment (draft)
      description: |
        Get comment (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentEnvelope' }
  /comment/list:
    post:
      summary: List comments (draft)
      description: |
        List comments (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentListEnvelope' }
  /comment/revise:
    post:
      summary: Revise comment (draft)
      description: |
        Revise comment (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentReviseRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentEnvelope' }
  /comment/status:
    post:
      summary: Update comment status (draft)
      description: |
        Update comment status (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentStatusRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentEnvelope' }
  /comment/report:
    post:
      summary: Report top-N largest comments (draft)
      description: |
        Report top-N largest comments (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentReportRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentReportEnvelope' }
  /inbox/create:
    post:
      summary: Create inbox notification (draft)
      description: |
        Create inbox notification (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. If this updates a revisioned record, expected_revision is required (428 if
        missing; 409 on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxEnvelope' }
  /inbox/get:
    post:
      summary: Get inbox notification (draft)
      description: |
        Get inbox notification (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxEnvelope' }
  /inbox/list:
    post:
      summary: List inbox notifications (draft)
      description: |
        List inbox notifications (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxListEnvelope' }
  /inbox/status:
    post:
      summary: Update inbox status (draft)
      description: |
        Update inbox status (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxStatusRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxEnvelope' }
  /inbox/state:
    post:
      summary: Update inbox state (draft)
      description: |
        Update inbox state (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters: [ { $ref: '#/components/parameters/OrgHeader' }, { $ref: '#/components/parameters/LogicalHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxStateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxEnvelope' }
  /search/comments:
    post:
      summary: Search comments (org-wide)
      description: Org-scoped full-text search across comments (ICS/SCM/PCM/CRM/PPM/Influencer/Accounting); results are best-effort and eventually consistent.
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 2500
      x-latency-p95-ms: 150
      x-latency-p99-ms: 400
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentSearchRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentSearchEnvelope' }
  /search/inbox:
    post:
      summary: Search inbox notifications (org-wide)
      description: Org-scoped full-text search across inbox notifications (ICS/SCM/PCM/CRM/PPM/Influencer/Accounting); results are best-effort and eventually consistent.
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 2500
      x-latency-p95-ms: 150
      x-latency-p99-ms: 400
      parameters: [ { $ref: '#/components/parameters/OrgHeader' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxSearchRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxSearchEnvelope' }
  /serial/register:
    post:
      operationId: serialRegister
      summary: Register a serial number with metadata
      description: |
        Idempotent upsert of a serial record with manufacture date, warranty, condition, UDI.
        Resolves G50 (serial metadata) and G53 (serial lookup).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 200
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [serial, reason, source_refs]
              properties:
                serial:
                  $ref: '#/components/schemas/SerialRecordDraft'
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                idempotency_key: { type: string }
              x-idempotency-scope: SERIAL_REGISTER
              x-idempotency-retention-hours: 24
              x-idempotency-replay: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SerialEnvelope' }
  /serial/get:
    post:
      operationId: serialGet
      summary: Get a serial record by serial_number + variant_id
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 500
      x-concurrency-target: 1000
      x-latency-p95-ms: 100
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [serial_number, variant_id]
              properties:
                serial_number: { type: string }
                variant_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SerialEnvelope' }
  /serial/lookup:
    post:
      operationId: serialLookup
      summary: Lookup serial by serial_number alone (returns all variants)
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 500
      x-concurrency-target: 1000
      x-latency-p95-ms: 200
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [serial_number]
              properties:
                serial_number: { type: string }
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SerialListEnvelope' }
  /serial/lookup-udi:
    post:
      operationId: serialLookupByUdi
      summary: Lookup serial records by UDI (FDA recall support)
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 500
      x-concurrency-target: 1000
      x-latency-p95-ms: 200
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [udi]
              properties:
                udi: { type: string }
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SerialListEnvelope' }
  /serial/list:
    post:
      operationId: serialList
      summary: List serial records by variant_id or status (paginated)
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                variant_id: { type: string }
                status: { type: string, enum: [registered, active, in_warranty, out_of_warranty, recalled, retired] }
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SerialListEnvelope' }
  /serial/update:
    post:
      operationId: serialUpdate
      summary: Update serial record metadata with expected_revision
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 200
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [serial_number, variant_id, reason, source_refs, expected_revision]
              properties:
                serial_number: { type: string }
                variant_id: { type: string }
                status: { type: string, enum: [registered, active, in_warranty, out_of_warranty, recalled, retired] }
                manufacture_date: { type: string }
                batch_id: { type: string }
                warranty_start: { type: string }
                warranty_expiry: { type: string }
                condition: { type: string, enum: [new, like_new, good, fair, poor, used, refurbished, damaged] }
                condition_notes: { type: string, maxLength: 2000, description: Free-text notes describing condition }
                condition_assessed_by: { type: string, description: User/agent who assessed condition }
                condition_assessed_at: { type: string, format: date-time, description: When condition was assessed }
                udi: { type: string }
                location_ref: { type: string }
                customer_ref: { type: string }
                custom_metadata: { type: object }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                expected_revision: { type: integer }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SerialEnvelope' }
  /serial/360:
    post:
      operationId: serial360
      summary: Composite serial 360 — returns serial record + all related warranty claims in one call
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 200
      x-concurrency-target: 500
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [serial_number, variant_id]
              properties:
                serial_number: { type: string }
                variant_id: { type: string }
      responses:
        '200':
          description: OK — serial record + warranty_claims array
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          serial: { $ref: '#/components/schemas/SerialRecord' }
                          warranty_claims: { type: array, items: { type: object } }
  /holdback/set:
    post:
      operationId: holdbackSet
      summary: Create or update a holdback rule for a facility (scope '*' = facility-wide, or variant_id for per-variant override)
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-idempotency-scope: orgcode+route+idempotency_key
              x-idempotency-retention-hours: 24
              x-idempotency-replay: return_original_response
              required: [holdback, reason, source_refs]
              properties:
                holdback:
                  type: object
                  required: [scope, holdback_type, holdback_value]
                  properties:
                    scope: { type: string, description: "'*' for facility-wide default or a variant_id" }
                    holdback_type: { type: string, enum: [absolute, percentage] }
                    holdback_value: { type: integer, minimum: 0, description: "For percentage: 0-100" }
                    min_available_after_holdback: { type: integer, minimum: 0 }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                idempotency_key: { type: string }
                expected_revision: { type: integer }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      holdback:
                        type: object
                        properties:
                          scope: { type: string }
                          holdback_type: { type: string, enum: [absolute, percentage] }
                          holdback_value: { type: integer }
                          min_available_after_holdback: { type: integer }
                          logical_guid: { type: string }
                          created_at: { type: string, format: date-time }
                          updated_at: { type: string, format: date-time }
                          revision: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }
  /holdback/get:
    post:
      operationId: holdbackGet
      summary: Fetch a holdback rule by scope
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 100
      x-latency-p99-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scope: { type: string, default: '*' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      holdback: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /holdback/list:
    post:
      operationId: holdbackList
      summary: List all holdback rules for a facility
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 150
      x-latency-p99-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit: { type: integer, minimum: 1, maximum: 256, default: 50 }
                next_token: { type: object }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      holdbacks: { type: array, items: { type: object } }
                      next_token: { type: object, nullable: true }
                      count: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }
  /atp/query:
    post:
      operationId: atpQuery
      summary: Compute channel-aware Available-to-Promise across facilities (read-only, no events)
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [variant_ids, facilities]
              properties:
                variant_ids: { type: array, items: { type: string }, maxItems: 50 }
                facilities:
                  type: array
                  items:
                    type: object
                    required: [logical_guid]
                    properties:
                      logical_guid: { type: string }
                      role: { type: string, default: source }
                      priority: { type: integer }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      variants:
                        type: array
                        items:
                          type: object
                          properties:
                            variant_id: { type: string }
                            total_on_hand: { type: integer }
                            total_available: { type: integer }
                            total_holdback: { type: integer }
                            total_reportable: { type: integer }
                            facilities:
                              type: array
                              items:
                                type: object
                                properties:
                                  logical_guid: { type: string }
                                  role: { type: string }
                                  priority: { type: integer }
                                  on_hand: { type: integer }
                                  available: { type: integer }
                                  holdback: { type: integer }
                                  reportable: { type: integer }
                      facility_count: { type: integer }
                      variant_count: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }
  /demand/signal/get:
    post:
      operationId: demandSignalGet
      summary: Get demand signal for a variant at a facility
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [variant_id]
              properties:
                variant_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      demand_signal: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /demand/signal/list:
    post:
      operationId: demandSignalList
      summary: List demand signals for a facility
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 500
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit: { type: integer, minimum: 1, maximum: 256, default: 50 }
                next_token: { type: object }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      demand_signals: { type: array, items: { type: object } }
                      next_token: { type: object, nullable: true }
                      count: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }
  /demand/signal/compute:
    post:
      operationId: demandSignalCompute
      summary: Compute demand signals for a facility from stock card entries (G83)
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 10
      x-concurrency-target: 50
      x-latency-p95-ms: 5000
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      computed_count: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }
  /snapshot/create:
    post:
      operationId: snapshotCreate
      summary: Capture a point-in-time inventory snapshot for a facility (G85)
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 5
      x-concurrency-target: 20
      x-latency-p95-ms: 10000
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                currency: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      snapshot: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /snapshot/get:
    post:
      operationId: snapshotGet
      summary: Get an inventory snapshot by ID
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [snapshot_id]
              properties:
                snapshot_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      snapshot: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /snapshot/list:
    post:
      operationId: snapshotList
      summary: List inventory snapshots for a facility
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 500
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit: { type: integer, minimum: 1, maximum: 256, default: 50 }
                next_token: { type: object }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      snapshots: { type: array, items: { type: object } }
                      next_token: { type: object, nullable: true }
                      count: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }
  /snapshot/detail:
    post:
      operationId: snapshotDetail
      summary: Get detail items (per-variant breakdown) of an inventory snapshot
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 500
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [snapshot_id]
              properties:
                snapshot_id: { type: string }
                limit: { type: integer, minimum: 1, maximum: 256, default: 50 }
                next_token: { type: object }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      details: { type: array, items: { type: object } }
                      next_token: { type: object, nullable: true }
                      count: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }