Чек-лист интегратора

Этот лист — спутник Companion-страницы MATx и расширенного PR-плана из репо packages/bkt-core/integration-patches/pr1-bookkeeping.md. Здесь — компактный чек-лист «что нажимать», без обоснований.

Прежде чем начать

• ☐ Версия Node ≥ 20 (NodeNext ESM-резолвер).
• ☐ Доступ на запись в БД проекта (миграции / Drizzle push).
• ☐ Прочитан Обзор пайплайна — чтобы все параметры были на одном языке.

Шаги

1. Подключить пакет

Один из двух вариантов:

# A) git submodule
git submodule add https://github.com/sapsan14/matx-hack.git vendor/matx-hack
cd vendor/matx-hack/packages/bkt-core && npm install && npm run build
# в package.json:
#   "@matx-hack/bkt-core": "file:./vendor/matx-hack/packages/bkt-core"

# B) tarball
cd packages/bkt-core && npm install && npm run build && npm pack
# в потребителе:
npm install /path/to/matx-hack-bkt-core-0.1.1.tgz

• ☐ import { recommend, applyAttempt, DEFAULT_BKT } from "@matx-hack/bkt-core" компилируется.

2. Прогнать миграцию БД

Создать таблицу состояния (см. SQL в pr1-bookkeeping.md, шаг 1).

• ☐ Таблица student_skill_state существует.
• ☐ Drizzle-схема обновлена (shared/schema.ts).

3. Подключить обновление в endpoint регистрации ответа

В обработчике сохранения результата (createResult или эквивалент):

• ☐ После db.insert(results) подгружается pKnown из student_skill_state.
• ☐ Вызов bktUpdate(prior, isCorrect, DEFAULT_BKT) вычисляет posterior.
• ☐ Upsert в student_skill_state сохраняет новое значение и инкрементирует attempts.

4. (Опционально) Подключить ZPD-селектор

Только если меняем выбор задачи — в PR-1 не трогаем.

• ☐ Endpoint выдачи следующей задачи использует recommend(state, pool, 1).
• ☐ Возвращается задача с pSolve ближайшим к 0.7.

5. Проверка глазами

После пары попыток одного юзера:

SELECT user_id, competency_id, p_known, attempts
FROM student_skill_state
ORDER BY last_updated DESC LIMIT 10;

• ☐ Свежий пользователь стартует с p_known = 0.2.
• ☐ Один правильный ответ: 0.2 → ~0.40.
• ☐ Два правильных подряд: ~0.40 → ~0.70.
• ☐ Один неправильный после: ~0.70 → ~0.45.

Откат

PR-1 чисто аддитивный: достаточно дропнуть таблицу student_skill_state и удалить блок BKT-апдейта в createResult. UI и старый getNextRecommendedQuestion не затрагиваются.

Быстрые ссылки

• Companion-страница MATx — общая мотивация и план PR-1/PR-2.
• Полный план PR-1 на GitHub.
• README пакета — quickstart и edge cases.
• EU AI Act — почему детерминированный BKT удобен с т.з. compliance.