@easiitix/collection-selector/README.md

Deterministic item selection engine with EV targeting and reserve safety.

# Collection Selector (npm package)

## Дисклеймер

- Проект предназначен исключительно для учебных целей.
- Использование исходного кода, сборок и артефактов за пределами учебного контекста запрещено.
- Любое распространение, публикация, коммерческая интеграция или передача третьим лицам запрещены.
- Владелец не несёт никакой ответственности за то, где, кем и каким образом данный продукт будет использоваться.
- Лицензия: `UNLICENSED` — права не предоставляются.

## Install (только для учебного ознакомления)

- Локальная сборка:
  1. `npm install`
  2. `npx tsc -p tsconfig.json`
  3. `npm pack` → создаёт `easiitix-collection-selector-<version>.tgz`
  4. В другом проекте (учебное ознакомление): `npm install ../path/to/easiitix-collection-selector-<version>.tgz`

## Usage (пример для учебных целей)

```ts
import { selectCollectionItem } from "@easiitix/collection-selector";

const result = selectCollectionItem({
  requestCost: 30,
  targetEvFraction: 0.92,
  serviceFeeRate: 0.08,
  currentReserve: 100000,
  itemPrices: [1, 3, 4, 5, 10, 20, 25, 30, 40, 50, 70, 100, 500, 1000, 2000, 3000, 4000, 5000, 6000],
  maxPriceMultiplier: 50,
  reserveSafetyFraction: 1.0,
  baseWeights: undefined,
  sequenceSeed: undefined
});

console.log(result);
// { addedToReserve: 27.6, selectedItemPrice: <number>, serviceFee: 2.4 }
```

## API

- `selectCollectionItem(opts: SelectItemOptions): SelectItemResult`
  - `SelectItemOptions`:
    - `requestCost: number`
    - `targetEvFraction: number` (0..1)
    - `serviceFeeRate: number` (0..1)
    - `currentReserve: number`
    - `itemPrices: number[]`
    - `maxPriceMultiplier?: number`
    - `reserveSafetyFraction?: number` (0..1]
    - `baseWeights?: number[]`
    - `sequenceSeed?: number | null`
  - `SelectItemResult`:
    - `addedToReserve: number` — добавлено в резерв после сборов
    - `selectedItemPrice: number` — выбранная цена предмета
    - `serviceFee: number` — размер сбора

## Invariants & Validation

- `serviceFeeRate` и `targetEvFraction` приводятся к диапазону `[0,1]`.
- `reserveSafetyFraction` приводится к `(0,1]`.
- Отрицательные входы sanitizируются до `0`.
- Выбор цены ограничен `min(currentReserve * reserveSafetyFraction, maxPriceMultiplier * requestCost)`.
- Если ограничение ≤ 0 или нет подходящих элементов → выбранная цена `0`.

## Sequence Helper

- Доступен детерминированный генератор последовательности: `createSequence(sequenceSeed?: number | null)` возвращает `{ next(): number }`.