@dolphy-app/extension-sdk 0.4.0 → 0.5.0

package/dist/index-I_CXC6Lj.d.ts

@@ -0,0 +1,1958 @@
+//#region packages/engine-contract/src/index.d.ts
+type UnitId = string;
+type EpochMs = number;
+type Grade = 1 | 2 | 3 | 4 | 5;
+type UnitKind = 'course' | 'lesson' | 'exercise';
+/** Любое значение JSON (хранилище и настройки расширений). */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+interface PageRequest {
+  limit?: number;
+  cursor?: string;
+}
+interface Page<T> {
+  items: T[];
+  nextCursor?: string;
+}
+type EngineErrorCode = 'INVALID_ARGUMENT' | 'NOT_FOUND' | 'ENGINE_CLOSED' | 'INCOMPATIBLE_CONTRACT' | 'LIBRARY_NOT_LOADED' | 'LIBRARY_INVALID' | 'ASSET_OUTSIDE_LIBRARY' | 'ASSET_TOO_LARGE' | 'ATTEMPT_NOT_FOUND' | 'ATTEMPT_CLOSED' | 'EXERCISE_TYPE_UNAVAILABLE' | 'PLACEMENT_SESSION_NOT_FOUND' | 'PLACEMENT_SESSION_ACTIVE' | 'PLACEMENT_BUDGET_EXHAUSTED' | 'SYNC_DEVICE_ID_CLASH' | 'SYNC_CONFLICT_NOT_FOUND' | 'SYNC_FOLDER_NOT_CONFIGURED' | 'STORE_BUSY' | 'STORE_READONLY' | 'STORE_CORRUPT' | 'REPOSITORY_EXISTS' | 'REPOSITORY_REJECTED' | 'GIT_FETCH_FAILED' | 'CATALOG_UNAVAILABLE' | 'EXTENSION_INSTALL_FAILED' |
+/** Запись в хранилище расширения превысила потолок; `details`: `extensionId`, `kind`, `limit`. */
+'EXTENSION_STORAGE_QUOTA' |
+/** Системного хранилища ключей нет (или оно не расшифровало значение): секрет расширения не записан и не прочитан. */
+'SECRETS_UNAVAILABLE' |
+/** Команда расширения не выполнена; `details`: `extensionId`, `commandId`, `reason` (`ExtensionCommandFailureReason`). */
+'EXTENSION_COMMAND_FAILED' |
+/** Импорт или экспорт расширения не выполнен; `details`: `extensionId`, `id`, `kind` (`import` | `export`), `reason` (`ExtensionTransferFailureReason`). */
+'EXTENSION_TRANSFER_FAILED' |
+/** An RPC call to the server part of an extension failed; `details`: `extensionId`, `name`, `reason` (`ExtensionRpcFailureReason`). The message of a failed handler reaches the caller as the error message. */
+'EXTENSION_RPC_FAILED' |
+/** Хук «до» расширения отменил операцию; `details`: `ExtensionHookFailureDetails`. Сообщение ошибки содержит имя расширения и текст его исключения; журнал и сессия не меняются. */
+'EXTENSION_HOOK_FAILED' | 'INTERNAL';
+interface EngineErrorDto {
+  code: EngineErrorCode;
+  message: string;
+  retryable: boolean;
+  details?: Record<string, unknown>;
+}
+type Severity = 'error' | 'warning' | 'info';
+/** Каталог компилятора: 36 кодов + `W_GRANULARITY`, `E_REFERENCE_FAILS` (engine-ts.md §1.1, F2) + `W_ORPHAN_EVENTS` (его выдаёт движок при открытии, не компилятор). Префикс = серьёзность по умолчанию. */
+type DiagnosticCode = 'E_IO' | 'E_JSON_PARSE' | 'E_SCHEMA' | 'W_UNKNOWN_KEY' | 'E_FRONTMATTER_UNTERMINATED' | 'E_FRONTMATTER_PARSE' | 'E_ENGINE_SCHEMA' | 'W_ENGINE_UNKNOWN_KEY' | 'E_ENGINE_DUPLICATE' | 'W_UNKNOWN_EXERCISE_TYPE' | 'E_EXERCISE_SPEC' | 'E_ID_EMPTY' | 'E_ID_DUPLICATE' | 'E_ID_MISMATCH' | 'E_DEP_MISSING' | 'E_DEP_SELF' | 'E_DEP_KIND' | 'E_CYCLE_DEPENDENCY' | 'E_CYCLE_SUPERSEDED' | 'E_CYCLE_ENCOMPASSED' | 'W_REDUNDANT_EDGE' | 'E_ENC_WEIGHT' | 'E_ENC_MISSING' | 'E_ENC_NOT_ANCESTOR' | 'E_SUP_MISSING' | 'W_ORPHAN_LESSON' | 'W_FAN_IN' | 'E_KEYPREREQ_MISSING' | 'E_KEYPREREQ_NOT_ANCESTOR' | 'E_NO_VERIFICATION' | 'I_NO_VERIFICATION' | 'W_UNSUPPORTED_GENERATOR' | 'E_ASSET_MISSING' | 'E_ASSET_ESCAPES_ROOT' | 'E_ASSET_TYPE' | 'W_ASSET_KIND_UNSUPPORTED' | 'W_KB_STRAY_FILE' | 'W_GRANULARITY' | 'E_REFERENCE_FAILS' | 'W_ORPHAN_EVENTS';
+interface Diagnostic {
+  code: DiagnosticCode;
+  severity: Severity;
+  message: string;
+  unitId?: UnitId;
+  /** Путь файла относительно корня библиотеки. */
+  path?: string;
+  /** Строка в `path` (1-based), где она детерминирована. */
+  line?: number;
+  /** Связанные юниты: полный путь цикла (`E_CYCLE_*`), цель `encompassed`, обходной пререквизит `W_REDUNDANT_EDGE`. */
+  related?: UnitId[];
+}
+interface DiagnosticSummary {
+  errors: number;
+  warnings: number;
+  infos: number;
+}
+/** `fresh` — артефакт соответствует библиотеке (stat или content-`revision`); `stale` — `revision` отличается; `missing` — файла нет или он не читается; `compiling` — идёт фоновая компиляция. */
+type ArtifactState = 'fresh' | 'stale' | 'missing' | 'compiling';
+interface LibraryInfo {
+  contractVersion: number;
+  root: string;
+  /** content-`revision` загруженной библиотеки (sha256 по отсортированным `path\0len\0bytes`). */
+  revision: string;
+  state: 'ready' | 'invalid';
+  artifact: ArtifactState;
+  counts: {
+    courses: number;
+    lessons: number;
+    exercises: number;
+    dependencyEdges: number;
+  };
+  diagnostics: DiagnosticSummary;
+  loadedAt: EpochMs;
+  loadMs: number;
+}
+interface AssetRef {
+  unitId: UnitId;
+  path: string;
+}
+interface WeightedRef {
+  id: UnitId;
+  weight: number;
+}
+interface UnitCommon {
+  id: UnitId;
+  name: string;
+  description?: string;
+  metadata: Record<string, string[]>;
+  dependencies: UnitId[];
+  encompassed: WeightedRef[];
+  superseded: UnitId[];
+}
+interface CourseDto extends UnitCommon {
+  kind: 'course';
+  lessonCount: number;
+  authors?: string[];
+  material?: AssetRef;
+  instructions?: AssetRef;
+}
+interface LessonDto extends UnitCommon {
+  kind: 'lesson';
+  courseId: UnitId;
+  exerciseCount: number;
+  material?: AssetRef;
+  instructions?: AssetRef;
+}
+type ExerciseContentDto = {
+  type: 'flashcard';
+  front: AssetRef;
+  back?: AssetRef;
+} | {
+  type: 'inlineFlashcard';
+  front: string;
+  back?: string;
+} | {
+  type: 'markdown';
+  ref: AssetRef;
+} | {
+  type: 'inlineMarkdown';
+  text: string;
+};
+/** Вид задания: окно ищет компонент ввода ответа в своём реестре по `type` (регистрация `addAnswerView`). */
+interface ExerciseTaskDto {
+  /** Id вида задания. */
+  type: string;
+  timeoutMs: number;
+  /** Расширение, зарегистрировавшее вид. */
+  extensionId: string;
+}
+interface ExerciseDto {
+  kind: 'exercise';
+  id: UnitId;
+  lessonId: UnitId;
+  courseId: UnitId;
+  name: string;
+  description?: string;
+  exerciseType: 'declarative' | 'procedural';
+  content: ExerciseContentDto;
+  task?: ExerciseTaskDto;
+  keyPrerequisites: UnitId[];
+}
+type UnitDto = CourseDto | LessonDto | ExerciseDto;
+interface GraphQuery {
+  rootIds?: UnitId[];
+  depth?: number;
+  kinds?: UnitKind[];
+  limit?: number;
+}
+interface GraphNodeDto {
+  id: UnitId;
+  kind: UnitKind;
+  name: string;
+  parentId?: UnitId;
+}
+/** `from` зависит от `to` (dependency), охватывает `to` (encompassed) или заменяет `to` (superseded). */
+interface GraphEdgeDto {
+  from: UnitId;
+  to: UnitId;
+  type: 'dependency' | 'encompassed' | 'superseded';
+  weight?: number;
+}
+interface GraphDto {
+  nodes: GraphNodeDto[];
+  edges: GraphEdgeDto[];
+  truncated: boolean;
+}
+interface AssetContent {
+  ref: AssetRef;
+  mime: 'text/markdown' | 'text/plain';
+  text: string;
+  bytes: number;
+}
+interface ValidateRequest extends PageRequest {
+  minSeverity?: Severity;
+  /** Прогнать эталонные решения через раннер и выдать `E_REFERENCE_FAILS` (M5). */
+  runChecks?: boolean;
+}
+interface ValidateResult extends Page<Diagnostic> {
+  /** content-`revision` файлов на момент проверки; может отличаться от `LibraryInfo.revision`. */
+  revision: string;
+  summary: DiagnosticSummary;
+  checksRun: boolean;
+}
+interface CompileRequest {
+  runChecks?: boolean;
+}
+interface CompileResult {
+  revision: string;
+  diagnosticsSummary: DiagnosticSummary;
+  /** false: есть ошибки (артефакт не пишется) или свежий артефакт уже лежит на диске. */
+  artifactWritten: boolean;
+}
+interface LibraryService {
+  getInfo(): Promise<LibraryInfo>;
+  getDiagnostics(req?: PageRequest & {
+    minSeverity?: Severity;
+  }): Promise<Page<Diagnostic>>;
+  validate(req?: ValidateRequest): Promise<ValidateResult>;
+  compile(req?: CompileRequest): Promise<CompileResult>;
+  reload(): Promise<LibraryInfo>;
+  listCourses(req?: PageRequest): Promise<Page<CourseDto>>;
+  listLessons(courseId: UnitId, req?: PageRequest): Promise<Page<LessonDto>>;
+  listExercises(lessonId: UnitId, req?: PageRequest): Promise<Page<ExerciseDto>>;
+  getUnit(id: UnitId): Promise<UnitDto>;
+  matchPrefix(prefix: string, kind?: UnitKind, req?: PageRequest): Promise<Page<UnitId>>;
+  getGraph(query?: GraphQuery): Promise<GraphDto>;
+  readAsset(ref: AssetRef): Promise<AssetContent>;
+}
+type FilterOp = 'All' | 'Any';
+type FilterType = 'Include' | 'Exclude';
+type KeyValueFilterWire = {
+  CourseFilter: {
+    key: string;
+    value: string;
+    filter_type: FilterType;
+  };
+} | {
+  LessonFilter: {
+    key: string;
+    value: string;
+    filter_type: FilterType;
+  };
+} | {
+  CombinedFilter: {
+    op: FilterOp;
+    filters: KeyValueFilterWire[];
+  };
+};
+type UnitFilterWire = {
+  CourseFilter: {
+    course_ids: UnitId[];
+  };
+} | {
+  LessonFilter: {
+    lesson_ids: UnitId[];
+  };
+} | {
+  MetadataFilter: {
+    filter: KeyValueFilterWire;
+  };
+} | 'ReviewListFilter' | {
+  Dependents: {
+    unit_ids: UnitId[];
+  };
+} | {
+  Dependencies: {
+    unit_ids: UnitId[];
+    depth: number;
+  };
+};
+type SessionPartWire = {
+  UnitFilter: {
+    filter: UnitFilterWire;
+    duration: number;
+  };
+} | {
+  SavedFilter: {
+    filter_id: string;
+    duration: number;
+  };
+} | {
+  NoFilter: {
+    duration: number;
+  };
+};
+interface StudySessionWire {
+  id: string;
+  description?: string;
+  parts?: SessionPartWire[];
+}
+type ExerciseFilterDto = {
+  UnitFilter: UnitFilterWire;
+} | {
+  StudySession: {
+    startTimeMs: EpochMs;
+    definition: StudySessionWire;
+  };
+};
+type MasteryWindowName = 'new' | 'target' | 'current' | 'easy' | 'mastered';
+interface UnitScoreDto {
+  unitId: UnitId;
+  kind: UnitKind;
+  /** 0..5; null = нет валидной оценки. В `getBatch` (паритет Trane) зависимость без оценки считается выполненной; в `getFrontier` — закрытой (§4). */
+  score: number | null;
+  avgTrials: number | null;
+  window: MasteryWindowName | null;
+}
+type UnitStatus = 'locked' | 'ready' | 'in-progress' | 'mastered' | 'blacklisted' | 'superseded';
+interface ProgressNodeDto {
+  id: UnitId;
+  kind: UnitKind;
+  status: UnitStatus;
+  score: number | null;
+  avgTrials: number | null;
+  attempts: number;
+  lastAttemptAt?: EpochMs;
+  dueExercises?: number;
+}
+interface ProgressQuery {
+  scope?: {
+    courseId: UnitId;
+  } | {
+    lessonId: UnitId;
+  } | {
+    unitIds: UnitId[];
+  };
+  includeExercises?: boolean;
+}
+type AttemptSource = 'self' | 'runner' | 'placement' | 'trane-import';
+interface AttemptRecordDto {
+  eventId: string;
+  exerciseId: UnitId;
+  grade: Grade;
+  at: EpochMs;
+  source: AttemptSource;
+}
+interface BatchRequest {
+  filter?: ExerciseFilterDto;
+}
+/** `reasons[i]` — причина показа `exercises[i]`; массивы одной длины. */
+interface BatchDto {
+  exercises: ExerciseDto[];
+  reasons: ItemReason[];
+  generatedAt: EpochMs;
+  sessionId: string;
+}
+/** Причина позиции в батче и плане дня: `new` — попыток нет; `review` — есть попытки; `remediation` — вставлено ремедиацией (§4.3). */
+type ItemReason = 'review' | 'new' | 'remediation';
+interface AttemptDto {
+  attemptId: string;
+  exercise: ExerciseDto;
+  startedAt: EpochMs;
+  verifiable: boolean;
+  /** Результат `project()` расширения; `null`, если упражнение не проверяемое. */
+  view: unknown;
+}
+interface SubmitAnswerRequest {
+  attemptId: string;
+  answer: unknown;
+}
+interface VerdictBase {
+  attemptId: string;
+  /** Число вердиктов `passed`/`failed` по попытке; `error` не считается. */
+  attemptsUsed: number;
+  durationMs: number;
+  feedback?: string;
+  /** Данные расширения, непрозрачны для движка (например, `{ rowCount }` у SQL). */
+  data?: unknown;
+}
+type VerdictDto = (VerdictBase & {
+  outcome: 'passed';
+}) |
+/** Вина ученика. `detail` (ожидаемые строки) — только при `EngineConfig.authorMode`. */
+(VerdictBase & {
+  outcome: 'failed';
+  reason: string;
+  detail?: string;
+}) |
+/** Не вина ученика: журнал не затрагивается, повтор `submitAnswer` разрешён. */
+(VerdictBase & {
+  outcome: 'error';
+  reason: string;
+});
+interface CompleteAttemptRequest {
+  attemptId: string;
+  grade?: Grade;
+  outcome?: 'gave-up';
+}
+interface RecordAttemptRequest {
+  requestId: string;
+  exerciseId: UnitId;
+  grade: Grade;
+  at?: EpochMs;
+  source?: AttemptSource;
+}
+interface RecordResultDto {
+  eventId: string;
+  exerciseId: UnitId;
+  grade: Grade;
+  at: EpochMs;
+  duplicate: boolean;
+  affected: UnitScoreDto[];
+  /** Только если порог ремедиации пересечён именно этой попыткой (§4.3). */
+  remediation?: RemediationDto;
+}
+interface FrontierRequest extends PageRequest {
+  courseId?: UnitId;
+}
+interface FrontierItemDto {
+  lessonId: UnitId;
+  courseId: UnitId;
+  exerciseCount: number;
+}
+interface DueRequest extends PageRequest {
+  minNeed?: number;
+  /** Область курсов (как `PlacementStartRequest.courseIds`): пусто или нет поля — все курсы; неизвестный курс — `NOT_FOUND`. */
+  courseIds?: UnitId[];
+}
+interface DueItemDto {
+  exerciseId: UnitId;
+  lessonId: UnitId;
+  /** `1 − retrievability`, 0..1; список отсортирован по убыванию. */
+  need: number;
+  /** R сейчас, 0..1. */
+  retrievability: number;
+  score: number;
+  lastAttemptAt: EpochMs;
+}
+interface PracticeService {
+  /**
+   * Хук `session.start`: `EXTENSION_HOOK_FAILED` — расширение отменило
+   * старт, сессия не создаётся и `session.started` не уходит.
+   */
+  startSession(): Promise<{
+    sessionId: string;
+    startedAt: EpochMs;
+  }>;
+  /**
+   * Окно сообщает, что сессия обучения закончилась: расширения с событием
+   * `session.finished` получают его один раз на `sessionId`. Идемпотентна:
+   * повтор и неизвестный `sessionId` ничего не отправляют (`emitted: false`).
+   * После неё следующий `getBatch` начинает новую сессию.
+   */
+  finishSession(req: {
+    sessionId: string;
+  }): Promise<{
+    emitted: boolean;
+  }>;
+  /**
+   * Хуки расширений: `session.start`, если батч открывает сессию, и
+   * `practice.batch` до возврата батча; `EXTENSION_HOOK_FAILED` — хук
+   * отменил операцию или ответил неверно, батч не возвращается, сессия и
+   * журнал не меняются.
+   */
+  getBatch(req?: BatchRequest): Promise<BatchDto>;
+  beginAttempt(req: {
+    exerciseId: UnitId;
+  }): Promise<AttemptDto>;
+  submitAnswer(req: SubmitAnswerRequest): Promise<VerdictDto>;
+  completeAttempt(req: CompleteAttemptRequest): Promise<RecordResultDto>;
+  recordAttempt(req: RecordAttemptRequest): Promise<RecordResultDto>;
+  getUnitScore(unitId: UnitId): Promise<UnitScoreDto>;
+  getAttempts(exerciseId: UnitId, req?: PageRequest): Promise<Page<AttemptRecordDto>>;
+  getProgress(query?: ProgressQuery, req?: PageRequest): Promise<Page<ProgressNodeDto>>;
+  getFrontier(req?: FrontierRequest): Promise<Page<FrontierItemDto>>;
+  getDue(req?: DueRequest): Promise<Page<DueItemDto>>;
+  resetProgress(req: {
+    unitId: UnitId;
+    requestId: string;
+  }): Promise<{
+    eventId: string;
+    duplicate: boolean;
+  }>;
+  /**
+   * Отменяет попытку: она перестаёт влиять на оценки, награды, фронтир,
+   * повторы, ремедиацию и статистику; в журнал пишется запись `retract`
+   * (`op: 'set'`), попытка остаётся в нём. `targetId` — `id` попытки
+   * (`eventId` результата записи) либо `requestId` завершённого входного
+   * теста: тогда отменяется вся его пачка. Повтор с тем же `requestId` ничего
+   * не пишет (`duplicate: true`); цель уже отменена — запись не пишется,
+   * `changed: false`. Неизвестная цель — `NOT_FOUND`.
+   */
+  undo(req: RetractRequest): Promise<RetractResult>;
+  /** Возвращает отменённую `undo` цель (`op: 'unset'`); семантика та же. */
+  redo(req: RetractRequest): Promise<RetractResult>;
+}
+interface RetractRequest {
+  targetId: string;
+  requestId: string;
+}
+interface RetractResult {
+  /** `id` записи отмены; `null`, если запись не понадобилась (`changed: false`). */
+  eventId: string | null;
+  /** Повтор `requestId`: прежний результат. */
+  duplicate: boolean;
+  /** Состояние цели изменилось. */
+  changed: boolean;
+}
+interface PlanRequest {
+  /** 1..200 (граница — самый большой замеренный размер плана, §10). */
+  maxItems: number;
+  /** uint32; при равных (состояние, seed) план одинаков. Без `seed` хост берёт его из `Rng` и возвращает в `DayPlanDto.seed`. */
+  seed?: number;
+  /** Область курсов: в план попадают упражнения (в том числе ремедиация) только этих курсов, порядок и чередование считаются внутри области. Пусто или нет поля — все курсы; неизвестный курс — `NOT_FOUND`. При равных (состояние, seed, область) план одинаков. */
+  courseIds?: UnitId[];
+}
+interface PlanCoverDto {
+  exerciseId: UnitId;
+  credit: number;
+}
+interface PlanItemDto {
+  exerciseId: UnitId;
+  reason: ItemReason;
+  /** Упражнения, чей повтор этот элемент сжимает неявным кредитом; только при `implicitCreditEnabled`. */
+  covers?: PlanCoverDto[];
+}
+interface DayPlanDto {
+  items: PlanItemDto[];
+  /** true, если интерливинг выполним и соблюдён (не более `plan.maxSameCourseRun` подряд из одного курса, общие теги разнесены на `plan.minTagDistance`). */
+  interleaveOk: boolean;
+  implicitCreditEnabled: boolean;
+  seed: number;
+  generatedAt: EpochMs;
+}
+interface PlanService {
+  /**
+   * Расширение с хуком `practice.batch` может переставить, убрать и добавить
+   * упражнения до возврата плана; `EXTENSION_HOOK_FAILED` — хук отменил или
+   * ответил неверно, план не возвращается.
+   */
+  getDay(req: PlanRequest): Promise<DayPlanDto>;
+}
+interface PlacementStartRequest {
+  /** Пусто или нет поля — все курсы библиотеки. */
+  courseIds?: UnitId[];
+  /** Максимум проб, целое 1..200 (граница — предположение [ВЫВОД]); иначе `INVALID_ARGUMENT`. */
+  budget: number;
+  seed?: number;
+}
+interface PlacementStartResult {
+  sessionId: string;
+  lessonCount: number;
+  budget: number;
+  seed: number;
+}
+interface PlacementProbeDto {
+  probeId: string;
+  lessonId: UnitId;
+  exerciseId: UnitId;
+}
+/** `grade` — самооценка («пройдено» ⇔ оценка ≥ 3, engine-ts.md §6a.3); `attempt` — итог открытой попытки с проверкой (последний `passed`/`failed`). */
+type PlacementResult = {
+  kind: 'grade';
+  grade: Grade;
+} | {
+  kind: 'attempt';
+  attemptId: string;
+};
+interface PlacementAnswerRequest {
+  probeId: string;
+  result: PlacementResult;
+}
+interface PlacementProgressDto {
+  asked: number;
+  budget: number;
+  /** Темы, ещё не решённые (`p` между порогами); 0 — тест можно завершать. */
+  unresolved: number;
+}
+interface PlacementFinishRequest {
+  sessionId: string;
+  requestId: string;
+}
+interface PlacementSummaryDto {
+  /** Идентификаторы уроков. */
+  known: UnitId[];
+  unknown: UnitId[];
+  uncertain: UnitId[];
+  /** Фронтир, вычисленный из `known`; завышен за счёт `uncertain`-границы. */
+  frontier: UnitId[];
+  /** Записано попыток `source: 'placement'`: по 2 на упражнение каждого `known`-урока. */
+  attemptsWritten: number;
+  duplicate: boolean;
+}
+interface PlacementStepResult {
+  /** Ответ снят или возвращён; `false` — снимать (возвращать) было нечего. */
+  changed: boolean;
+  progress: PlacementProgressDto;
+}
+interface PlacementService {
+  start(req: PlacementStartRequest): Promise<PlacementStartResult>;
+  /** `null` — проб больше нет (бюджет исчерпан или все темы решены). До ответа на выданную пробу возвращает ту же пробу. */
+  nextProbe(sessionId: string): Promise<PlacementProbeDto | null>;
+  answer(req: PlacementAnswerRequest): Promise<PlacementProgressDto>;
+  /**
+   * Снимает последний ответ открытой сессии: следующая `nextProbe` выдаёт ту
+   * же тему. Каждый вызов — один шаг назад. Завершённая, прерванная и
+   * неизвестная сессия — `PLACEMENT_SESSION_NOT_FOUND`.
+   */
+  undo(sessionId: string): Promise<PlacementStepResult>;
+  /** Возвращает последний снятый `undo` ответ; новый `answer` сбрасывает возврат. */
+  redo(sessionId: string): Promise<PlacementStepResult>;
+  finish(req: PlacementFinishRequest): Promise<PlacementSummaryDto>;
+  abort(req: {
+    sessionId: string;
+  }): Promise<void>;
+}
+interface RemediationStepDto {
+  /** Пререквизит-юнит (урок); в порядке `engine.keyPrerequisites`, иначе прямые зависимости урока с наименьшей R. */
+  unitId: UnitId;
+  source: 'key-prerequisite' | 'lesson-dependency';
+  /** Упражнения шага: наименьшая R, не начатые — по порядку id; всего по плану не больше `remediation.maxItems`. */
+  exerciseIds: UnitId[];
+  /** Успех на каждом упражнении шага после триггера. */
+  done: boolean;
+}
+interface RemediationDto {
+  exerciseId: UnitId;
+  /** true — триггер сработал и не снят. */
+  active: boolean;
+  triggeredAt?: EpochMs;
+  steps: RemediationStepDto[];
+}
+interface RemediationService {
+  getPlan(req: {
+    exerciseId: UnitId;
+  }): Promise<RemediationDto>;
+}
+interface FlagService {
+  list(req?: PageRequest): Promise<Page<UnitId>>;
+  has(unitId: UnitId): Promise<boolean>;
+  add(unitId: UnitId): Promise<void>;
+  remove(unitId: UnitId): Promise<void>;
+  /** Раскрывает префикс в id на момент вызова и пишет по записи на юнит. */
+  removePrefix(prefix: string): Promise<{
+    removed: UnitId[];
+  }>;
+}
+interface SavedFilterDto {
+  id: string;
+  description: string;
+  filter: UnitFilterWire;
+}
+interface FilterStoreService {
+  list(): Promise<Array<{
+    id: string;
+    description: string;
+  }>>;
+  get(id: string): Promise<SavedFilterDto>;
+  save(filter: SavedFilterDto): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+interface SessionStoreService {
+  list(): Promise<Array<{
+    id: string;
+    description: string;
+  }>>;
+  get(id: string): Promise<StudySessionWire>;
+  save(session: StudySessionWire): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+interface CurationService {
+  blacklist: FlagService;
+  reviewList: FlagService;
+  filters: FilterStoreService;
+  sessions: SessionStoreService;
+}
+interface MasteryWindowDto {
+  percentage: number;
+  range: [number, number];
+}
+interface ImplicitCreditOptionsDto {
+  /** По умолчанию false: выигрыш измерен только в круговой модели (engine-ts.md §6a.2). */
+  enabled: boolean;
+  /** Затухание по глубине охвата, 0 < λ ≤ 1 [диапазон — ВЫВОД]. */
+  lambda: number;
+  /** Кредит ниже порога отбрасывается, 0 < minCredit ≤ 1 [диапазон — ВЫВОД]. */
+  minCredit: number;
+  /** Множитель на кредит. Не измерен: подбирается A/B на реальных ответах [НЕ ПОДТВЕРЖДЕНО]. */
+  kappa: number;
+}
+interface RemediationOptionsDto {
+  failThreshold: number;
+  maxItems: number;
+}
+interface PlanOptionsDto {
+  targetRetention: number;
+  minNewFraction: number;
+  maxSameCourseRun: number;
+  minTagDistance: number;
+}
+interface SchedulerOptionsDto {
+  batchSize: number;
+  relearnFraction: number;
+  masteryWindows: {
+    new: MasteryWindowDto;
+    target: MasteryWindowDto;
+    current: MasteryWindowDto;
+    easy: MasteryWindowDto;
+    mastered: MasteryWindowDto;
+  };
+  passingScore: {
+    minScore: number;
+    minFraction: number;
+    minAvgTrials: number;
+  };
+  supersedingScore: number;
+  numTrials: number;
+  numRewards: number;
+  maxLessonsInProgress: number;
+  /** Неявный повтор (FIRe), по умолчанию `{ enabled: false, lambda: 0.9, minCredit: 0.2, kappa: 1 }`. */
+  implicitCredit: ImplicitCreditOptionsDto;
+  /** По умолчанию `{ failThreshold: 2, maxItems: 3 }` — предположения [НЕ ПОДТВЕРЖДЕНО]. */
+  remediation: RemediationOptionsDto;
+  /** По умолчанию `{ targetRetention: 0.9, minNewFraction: 0.25, maxSameCourseRun: 2, minTagDistance: 2 }`. */
+  plan: PlanOptionsDto;
+}
+type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K]; };
+interface ScorerInfoDto {
+  kind: 'fsrs-hybrid' | 'power-law';
+  memoryModelId: string;
+  ratingMap: 'runner' | 'anki';
+  numTrials: number;
+  parametersHash: string;
+}
+interface PreferencesDto {
+  ignoredPaths: string[];
+  schedulerBatchSize?: number;
+}
+/** `system` — язык системы; renderer сам выбирает из поддерживаемых. */
+type LocaleMode = 'system' | 'ru' | 'en';
+/** Настройки интерфейса; хранятся вместе с остальными настройками в `engine.db`. */
+interface UiSettingsDto {
+  /** Встроенный режим или id темы расширения. */
+  theme: string;
+  locale: LocaleMode;
+  /** Курс в фокусе: клиент передаёт его в `courseIds` плана и повторений. Нет поля — все курсы. Движок не проверяет, что курс есть в библиотеке: курс могли убрать, клиент сверяет сам. */
+  activeCourseId?: UnitId;
+  /** Ширина панели теории в сессии и вход-тесте, px. Нет поля — умолчание клиента. */
+  materialWidth?: number;
+  /** Панель теории скрыта. Нет поля — показана. */
+  materialCollapsed?: true;
+  /** Исход обучающих туров по их id; нет записи — тур ещё не предлагали. */
+  tours?: Record<string, TourStatus>;
+}
+/** Как закончился тур: дошёл до конца или пропущен. */
+type TourStatus = 'completed' | 'skipped';
+/**
+ * `activeCourseId: null` снимает фокус, `materialWidth: null` возвращает умолчание,
+ * `materialCollapsed: false` показывает панель; `tours` меняет только перечисленные
+ * ключи, `null` удаляет запись о туре.
+ */
+type UiSettingsPatch = Partial<Omit<UiSettingsDto, 'activeCourseId' | 'materialWidth' | 'materialCollapsed' | 'tours'>> & {
+  activeCourseId?: UnitId | null;
+  materialWidth?: number | null;
+  materialCollapsed?: boolean;
+  tours?: Record<string, TourStatus | null>;
+};
+/** Настройки обучения; хранятся вместе с остальными настройками в `engine.db`. */
+interface LearningSettingsDto {
+  /** `passAtN` или id правила оценки расширения. */
+  gradePolicy: string;
+}
+interface SettingsService {
+  getScheduler(): Promise<SchedulerOptionsDto>;
+  /** Валидирует (`verify` как при открытии), применяет ко всем компонентам сразу. */
+  setScheduler(patch: DeepPartial<SchedulerOptionsDto>): Promise<SchedulerOptionsDto>;
+  resetScheduler(): Promise<SchedulerOptionsDto>;
+  getPreferences(): Promise<PreferencesDto>;
+  setPreferences(prefs: PreferencesDto): Promise<{
+    restartRequired: boolean;
+  }>;
+  getScorer(): Promise<ScorerInfoDto>;
+  getUi(): Promise<UiSettingsDto>;
+  /** Валидирует и сохраняет; возвращает итоговые настройки. */
+  setUi(patch: UiSettingsPatch): Promise<UiSettingsDto>;
+  getLearning(): Promise<LearningSettingsDto>;
+  /** Валидирует вид id (существование правила не проверяется) и сохраняет; возвращает итоговые настройки. */
+  setLearning(patch: Partial<LearningSettingsDto>): Promise<LearningSettingsDto>;
+  getKeybindings(): Promise<KeybindingsSettingsDto>;
+  /**
+   * Применяет патч целиком или не применяет: набор команды заменяется,
+   * `null` возвращает умолчания. Отклоняет (`INVALID_ARGUMENT`,
+   * `details.field`/`reason`/`command`/`other`) неверные клавиши и условия,
+   * превышение лимитов, повторы и пересечения пользовательских привязок
+   * разных команд. Возвращает итоговые привязки.
+   */
+  setKeybindings(patch: KeybindingsPatch): Promise<KeybindingsSettingsDto>;
+}
+/** Привязка пользователя: запись клавиш (`Mod+Shift+L`, `Mod+K Mod+S`) и условие `when` (`null` — без условия). */
+interface KeybindingEntryDto {
+  key: string;
+  when: string | null;
+}
+/** Пользовательские привязки по ключам команд (`app:<id>`, `extension:<extensionId>:<id>`); набор заменяет привязки команды из кода и расширений целиком, пустой — «снято». Хранятся в `engine.db`. */
+interface KeybindingsSettingsDto {
+  commands: Record<string, KeybindingEntryDto[]>;
+}
+/** Ключ команды → новый набор или `null` (сбросить к умолчаниям). */
+type KeybindingsPatch = Record<string, KeybindingEntryDto[] | null>;
+/** Вектор для дельта-экспорта: `{deviceId: contiguous}` — непрерывный префикс seq (1..contiguous без пропусков), не `maxSeq`. */
+type StateVector = Record<string, number>;
+/** Дыры за префиксом по устройствам: seq, записи которых уже есть, но предыдущих нет. */
+type MissingSeqs = Record<string, number[]>;
+/**
+ * `at` — время события по HLC-правилу (engine-ts.md §5.1): `max(min(now, now + 5 мин), maxAtУвиденный + 1, свойПрошлыйAt)`.
+ * Порядок везде `(at, deviceId, seq)`, при равных `(deviceId, seq)` — `id`. `recordedAt` — wall-clock записи, порядок не задаёт.
+ */
+interface LogEntryBaseDto {
+  id: string;
+  deviceId: string;
+  seq: number;
+  at: EpochMs;
+  recordedAt: EpochMs;
+}
+interface AttemptEntryDto extends LogEntryBaseDto {
+  kind: 'attempt';
+  exerciseId: UnitId;
+  grade: Grade;
+  source: AttemptSource;
+}
+interface UnitFlagEntryDto extends LogEntryBaseDto {
+  kind: 'unit_flag';
+  unitId: UnitId;
+  flag: 'blacklist' | 'review';
+  op: 'set' | 'unset';
+}
+interface ProgressResetEntryDto extends LogEntryBaseDto {
+  kind: 'progress_reset';
+  unitId: UnitId;
+  /** `revision` библиотеки на момент записи: диагностика расхождения версий курса между устройствами. */
+  libraryRevision?: string;
+}
+interface RetractEntryDto extends LogEntryBaseDto {
+  kind: 'retract';
+  /** `id` попытки или общая часть `id` пачки `<targetId>#<i>`. */
+  targetId: string;
+  op: 'set' | 'unset';
+}
+type LogEntryDto = AttemptEntryDto | UnitFlagEntryDto | ProgressResetEntryDto | RetractEntryDto;
+interface SyncStateDto {
+  deviceId: string;
+  vector: StateVector;
+  missing: MissingSeqs;
+  entryCount: number;
+  /** Неразрешённые конфликты. */
+  conflictCount: number;
+}
+interface ExportRequest {
+  since?: StateVector;
+  limit?: number;
+}
+interface ExportResult {
+  entries: LogEntryDto[];
+  next?: StateVector;
+}
+interface ImportResult {
+  inserted: number;
+  duplicates: number;
+  /** Структурно неверные записи. Конфликты (`id-content`, `seq-two-ids`, `clock-skew`) сюда не попадают. */
+  rejected: Array<{
+    id: string;
+    reason: string;
+  }>;
+  /** Новые конфликты, обнаруженные этим импортом. */
+  conflicts: number;
+  rebuilt: boolean;
+}
+interface RebuildResult {
+  entries: number;
+  ms: number;
+}
+interface TraneImportResult {
+  attempts: number;
+  flags: number;
+  skipped: number;
+}
+interface SyncConflictDto {
+  conflictId: string;
+  /**
+   * `id-content` — тот же `id`, другое содержимое; `seq-two-ids` — тот же `(deviceId, seq)`, другой `id`;
+   * `clock-skew` — запись с `at > recordedAt + 24 ч` (карантин по часам) [ВЫВОД, в спайке не реализовано].
+   */
+  reason: 'id-content' | 'seq-two-ids' | 'clock-skew';
+  /** Все стороны конфликта; скрыты от проекций, пока конфликт открыт. */
+  entries: LogEntryDto[];
+  /**
+   * `entryHash` (sha256 канонического JSON записи) каждой стороны — в том же порядке, что и `entries`.
+   * В `id-content` у сторон общий `id`; конкретную сторону выбирают по `entryHash` в `ResolveConflictRequest.keep`.
+   */
+  entryHashes: string[];
+  detectedAt: EpochMs;
+}
+interface ResolveConflictRequest {
+  conflictId: string;
+  /**
+   * `id` записи либо её `entryHash` (из `SyncConflictDto.entryHashes`), которую вернуть в проекции;
+   * `'none'` — оставить скрытыми все. В `id-content` у сторон общий `id` — по `id` берётся первая сторона
+   * в каноническом порядке, точную сторону выбирают по `entryHash`.
+   */
+  keep: string | 'none';
+}
+interface ResolveConflictResult {
+  conflictId: string;
+  kept: string | null;
+  rebuilt: boolean;
+}
+interface FolderSyncConfigureRequest {
+  dir: string;
+}
+interface FolderSyncReport {
+  inserted: number;
+  duplicates: number;
+  /** Число отвергнутых записей (у `sync.import` — массив с причинами). */
+  rejected: number;
+  /** Сегменты, которые не применены и повторятся в следующем раунде. */
+  pending: number;
+  headErrors: string[];
+  corruptSegments: string[];
+  pendingSegments: string[];
+  /** Применённые сегменты `device/name`. */
+  applied: string[];
+  /** Опубликованный хвост своего журнала. */
+  published: {
+    segments: number;
+    entries: number;
+  };
+  conflicts: number;
+  rebuilt: boolean;
+}
+interface FolderRestoreResult {
+  /** `catch-up` — свой хвост в папке длиннее локального: догнать и продолжить с `maxSeq + 1`; `fork` — данных нет нигде: новый `deviceId`. */
+  action: 'none' | 'catch-up' | 'fork';
+  newDeviceId?: string;
+}
+interface FolderSyncService {
+  /** Запоминает общую папку сегментов в `dataDir/settings/sync.json`; каталог должен существовать. */
+  configure(req: FolderSyncConfigureRequest): Promise<{
+    dir: string;
+  }>;
+  /** Один раунд: публикация своего хвоста, затем применение чужих сегментов. */
+  sync(): Promise<FolderSyncReport>;
+  /** Вызывать при старте и после восстановления из бэкапа. */
+  checkRestore(): Promise<FolderRestoreResult>;
+}
+interface SyncService {
+  getState(): Promise<SyncStateDto>;
+  exportSince(req?: ExportRequest): Promise<ExportResult>;
+  import(entries: LogEntryDto[]): Promise<ImportResult>;
+  rebuild(): Promise<RebuildResult>;
+  importFromTrane(req: {
+    traneDir: string;
+  }): Promise<TraneImportResult>;
+  getConflicts(req?: PageRequest): Promise<Page<SyncConflictDto>>;
+  resolveConflict(req: ResolveConflictRequest): Promise<ResolveConflictResult>;
+  readonly folder: FolderSyncService;
+}
+type EngineEvent = {
+  type: 'progress';
+  unitIds: UnitId[];
+  at: EpochMs;
+} | {
+  type: 'library-reloaded';
+  revision: string;
+  errors: number;
+  warnings: number;
+} | {
+  type: 'library-compiled';
+  revision: string;
+  artifactWritten: boolean;
+  errors: number;
+  warnings: number;
+} | {
+  type: 'state-rebuilt';
+  entries: number;
+  ms: number;
+} | {
+  type: 'sync-conflict';
+  conflictIds: string[];
+  unresolved: number;
+} | {
+  type: 'remediation-triggered';
+  exerciseId: UnitId;
+  steps: number;
+  at: EpochMs;
+} | {
+  type: 'settings-changed';
+  scope: 'scheduler' | 'preferences' | 'filters' | 'sessions' | 'blacklist' | 'reviewList' | 'ui' | 'learning' | 'extensions' | 'keybindings' |
+  /** Значения настроек или хранилище расширения; `extensionId` — чьи. */
+  'extensionValues';
+  extensionId?: string;
+} | {
+  type: 'extensions-changed';
+} |
+/**
+ * Здоровье расширений или состояние хоста расширений изменилось (сбой,
+ * активация, приостановка, перезапуск хоста): окно перечитывает
+ * `extensions.diagnostics()`.
+ */
+{
+  type: 'extension-health-changed';
+} |
+/**
+ * Набор вкладов расширений изменился: движок и хост расширений закончили
+ * применять установку, удаление, включение, доверие или правку в режиме
+ * разработчика. Окно перечитывает `extensions.contributions()`.
+ */
+{
+  type: 'contributions-changed';
+  generation: number;
+} | {
+  type: 'repository-progress';
+  id: string;
+  phase: RepositoryPhase;
+  /** Байты или объекты — по фазе; `total` неизвестен, пока сервер его не сообщил. */
+  loaded?: number;
+  total?: number;
+} |
+/**
+ * Закончилась проверка обновлений репозиториев курсов (`repositories.checkUpdates`
+ * или проверка при запуске). `available` — `id` репозиториев с `availableCommit`
+ * в порядке `repositories.list()`; пусто, если обновлений нет. Окно перечитывает
+ * `repositories.list()`. Не приходит, если не проверялся ни один репозиторий.
+ */
+{
+  type: 'repository-updates-checked';
+  available: string[];
+};
+interface EngineDiagnosticsDto {
+  contractVersion: number;
+  engineVersion: string;
+  uptimeMs: number;
+  entryCount: number;
+  dbBytes?: number;
+  timings: {
+    openLibraryMs: number;
+    rebuildMs: number;
+    batch: {
+      count: number;
+      p50Ms: number;
+      p95Ms: number;
+    };
+    recordAttemptP95Ms: number;
+  };
+  cache: {
+    exerciseHitRatio: number;
+    entries: number;
+  };
+  dirty: boolean;
+}
+/** Этап `repositories.add` / `repositories.update` (событие `repository-progress`). */
+type RepositoryPhase = 'resolve' | 'fetch' | 'export' | 'validate' | 'reload';
+/** `updating` — идёт операция; `error` — последняя операция отклонена или снимок пропал (`lastError`). */
+type RepositoryStatus = 'ready' | 'updating' | 'error';
+/** Git-репозиторий с курсами: снимок коммита лежит в `<libraryRoot>/repositories/<id>`. */
+interface RepositoryDto {
+  /** Стабильный slug нормализованного URL. */
+  id: string;
+  /** Нормализованный URL (`http(s)`, без учётных данных). */
+  url: string;
+  /** Ветка или тег; `null` — ветка по умолчанию удалённого репозитория. */
+  ref: string | null;
+  /** Полный SHA-1 загруженного коммита. */
+  commit: string;
+  fetchedAt: EpochMs;
+  status: RepositoryStatus;
+  /** Курсы, пришедшие из этого репозитория. */
+  courseIds: UnitId[];
+  /** Курсы загруженного коммита, которых нет в библиотеке из-за выбора ученика; у репозитория без выбора пусто. */
+  skippedCourseIds: UnitId[];
+  lastError?: EngineErrorDto;
+  /**
+   * Коммит на сервере, если он отличается от загруженного (последняя проверка
+   * этого запуска движка, в `engine.db` не пишется); нет — обновления нет или
+   * проверки ещё не было.
+   */
+  availableCommit?: string;
+  /** Когда репозиторий в последний раз успешно сверен с сервером в этом запуске; нет — не сверялся. */
+  checkedAt?: EpochMs;
+}
+/** Вход `repositories.preview`: как у `add`, без выбора курсов. */
+interface PreviewRepositoryRequest {
+  url: string;
+  ref?: string;
+}
+interface AddRepositoryRequest {
+  url: string;
+  ref?: string;
+  /**
+   * Курсы репозитория, которые нужно поставить (непустой список без повторов).
+   * Нет поля — все курсы коммита, и новые курсы при `update` тоже ставятся.
+   */
+  courseIds?: UnitId[];
+  /** `RepositoryPreviewDto.previewId` того же адреса и ветки: установка без загрузки. */
+  previewId?: string;
+}
+interface UpdateRepositoryOptions {
+  /** Новый выбор курсов (как `AddRepositoryRequest.courseIds`); нет поля — прежний. */
+  courseIds?: UnitId[];
+  /** `RepositoryPreviewDto.previewId` того же репозитория: установка без загрузки. */
+  previewId?: string;
+}
+interface RemoveRepositoryOptions {
+  /**
+   * Сбросить прогресс курсов репозитория (`progress_reset` на каждый курс из
+   * `RepositoryDto.courseIds`, на других устройствах — после синхронизации).
+   * По умолчанию `false`: журнал не меняется, прогресс вернётся при повторном
+   * добавлении.
+   */
+  removeProgress?: boolean;
+}
+/** Курс репозитория в предпросмотре (`repositories.preview`). */
+interface RepositoryCourseDto {
+  id: UnitId;
+  title: string;
+  /** Каталог курса от корня репозитория. */
+  path: string;
+  lessonCount: number;
+  /**
+   * Курсы того же репозитория, без которых этот не загрузится: зависимости,
+   * `superseded` и `encompassed` на юниты других курсов, курсы-предки по
+   * вложенности каталогов.
+   */
+  requires: UnitId[];
+  /** Диагностики сканера в каталоге курса. */
+  errors: number;
+  warnings: number;
+  /** До пяти первых текстов ошибок; не переводятся. */
+  messages: string[];
+  /** Курс уже пришёл из этого репозитория (запись реестра с тем же URL). */
+  installed: boolean;
+  /** Курс с таким `id` уже есть в библиотеке из другого источника. */
+  inLibrary: boolean;
+}
+interface RepositoryPreviewDto {
+  /** Нормализованный URL. */
+  url: string;
+  ref: string | null;
+  /** Полный SHA-1 просмотренного коммита. */
+  commit: string;
+  /** Все курсы коммита в порядке обхода каталогов. */
+  courses: RepositoryCourseDto[];
+  /**
+   * Токен скачанного снимка: движок держит его до 5 минут (не больше двух
+   * снимков) и ставит курсы из него, если передать токен в `add` или `update`.
+   * Токен одноразовый; просроченный, израсходованный или чужой токен не
+   * ошибка — репозиторий скачивается заново.
+   */
+  previewId: string;
+}
+interface UpdateRepositoryResult {
+  /** `false` — коммит на сервере совпал с загруженным, ничего не скачивалось. */
+  changed: boolean;
+  repository: RepositoryDto;
+}
+interface RepositoriesService {
+  list(): Promise<RepositoryDto[]>;
+  /**
+   * Скачивает репозиторий во временный каталог и возвращает его курсы для
+   * выбора; библиотека, реестр и каталоги библиотеки не меняются.
+   * `INVALID_ARGUMENT`, `GIT_FETCH_FAILED`, `REPOSITORY_REJECTED` (правила снимка).
+   */
+  preview(req: PreviewRepositoryRequest): Promise<RepositoryPreviewDto>;
+  /**
+   * `INVALID_ARGUMENT`, `REPOSITORY_EXISTS`, `GIT_FETCH_FAILED`,
+   * `REPOSITORY_REJECTED` (в том числе `unknown-course` и `missing-requirement`
+   * при `courseIds`).
+   */
+  add(req: AddRepositoryRequest): Promise<RepositoryDto>;
+  /**
+   * Обновляет репозиторий; `options.courseIds` заменяет выбор курсов.
+   * `NOT_FOUND`, `INVALID_ARGUMENT`, `GIT_FETCH_FAILED`, `REPOSITORY_REJECTED`.
+   */
+  update(id: string, options?: UpdateRepositoryOptions): Promise<UpdateRepositoryResult>;
+  /**
+   * Снимок и запись удаляются, курсы пропадают из библиотеки. С
+   * `options.removeProgress` прогресс курсов сбрасывается (журнал только
+   * дополняется), иначе журнал не меняется. `NOT_FOUND`, `INVALID_ARGUMENT`.
+   */
+  remove(id: string, options?: RemoveRepositoryOptions): Promise<void>;
+  /** `true`, если операция над репозиторием шла и прервана. */
+  cancel(id: string): Promise<boolean>;
+  /**
+   * Сверяет коммиты репозиториев с сервером без скачивания объектов и
+   * возвращает то же, что `list()`. Недоступный репозиторий пропускается
+   * (его прежний результат остаётся), репозиторий с идущей операцией не
+   * проверяется; вызов не падает из-за сети. Публикует `repository-updates-checked`.
+   */
+  checkUpdates(): Promise<RepositoryDto[]>;
+}
+type ExtensionOriginDto = 'bundled' | 'user' | 'dev';
+/**
+ * Подпись расширения: строка без перевода (показывается как есть) или тексты
+ * по языкам (`en` обязателен и служит запасным). Тот же тип, что `LocalizedText`
+ * в `@dolphy-app/extension-api` (контракт от него не зависит).
+ */
+type LocalizedTextDto = string | {
+  readonly en: string;
+  readonly ru?: string;
+};
+/**
+ * Состояние расширения. `dependencies-unmet` — включено, но не загружено:
+ * зависимость отсутствует, отключена, не загружена или не подходит по версии
+ * (причины — в `diagnostics`), вкладов нет. Отключение пользователем и
+ * безопасный режим важнее: такое расширение — `disabled`.
+ */
+type ExtensionStateDto = 'loaded' | 'overridden' | 'invalid' | 'disabled' | 'dependencies-unmet';
+/** Закрытый список кодов диагностик расширения; интерфейс строит текст по коду и данным. */
+declare const EXTENSION_DIAGNOSTIC_CODES: readonly ["manifest-unreadable", "manifest-invalid", "id-mismatch", "requires-app", "unavailable-platform", "claim-clash", "load-failed", "overridden-by", "safe-mode", "dependency-missing", "dependency-disabled", "dependency-version", "dependency-unmet", "dependency-cycle"];
+type ExtensionDiagnosticCode = (typeof EXTENSION_DIAGNOSTIC_CODES)[number];
+/** Значения `data` диагностики: строки, числа и списки строк. */
+type ExtensionDiagnosticValue = string | number | string[];
+/**
+ * Причина состояния расширения. Данные по кодам:
+ * `manifest-unreadable` — `reason`; `manifest-invalid` — `issues` (`путь: сообщение`);
+ * `id-mismatch` — `expected`, `actual`; `requires-app` — `minAppVersion`;
+ * `unavailable-platform` — `platform`; `claim-clash` — `kind`, `name`, `by`;
+ * `load-failed` — `reason` (код не загрузился или `server` не уложился в срок, регистрация расширения отвергнута целиком); `overridden-by` — `origin`, `version`; `safe-mode` — без данных;
+ * `dependency-missing` — `id`, `range` (нет, если диапазон не задан): расширения с таким id нет;
+ * `dependency-disabled` — `id`, `range`: зависимость отключена пользователем, отозвана или безопасным режимом;
+ * `dependency-version` — `id`, `range`, `found`: установлена версия вне диапазона;
+ * `dependency-unmet` — `id`, `range`: зависимость включена, но сама не загружена (её зависимости не выполнены);
+ * `dependency-cycle` — `cycle` (id расширений цикла): расширения зависят друг от друга.
+ */
+interface ExtensionDiagnosticDto {
+  code: ExtensionDiagnosticCode;
+  data: Record<string, ExtensionDiagnosticValue>;
+}
+interface ExtensionInfoDto {
+  /** Id манифеста; у некорректного расширения — имя каталога. */
+  id: string;
+  /** `null`, если манифест не удалось прочитать. */
+  version: string | null;
+  origin: ExtensionOriginDto;
+  state: ExtensionStateDto;
+  /** Серверные вклады по точкам (id); пусто, если расширение не `loaded`/`overridden`. */
+  contributes: ExtensionContributesDto;
+  /** Почему некорректно, кем перекрыто; пусто у загруженного и отключённого пользователем. */
+  diagnostics: ExtensionDiagnosticDto[];
+  /** `false` у расширений из поставки, перекрытых и некорректных: переключатели недоступны. */
+  toggleable: boolean;
+  /** Название из манифеста; `null` — не задано. */
+  name: string | null;
+  description: string | null;
+  /** GitHub-логин автора из манифеста. */
+  author: string | null;
+  /** Зависимости из манифеста; `[]` — нет или манифест не прочитан. */
+  dependencies: ExtensionDependencyDto[];
+  /** Значок из манифеста как `data:image/png|webp;base64,…`; `null` — значка нет или манифест не прочитан. */
+  icon: string | null;
+  /** Явные теги из манифеста; `[]` — нет или манифест не прочитан. */
+  tags: string[];
+  /** Установлено из каталога; `null` — скопировано вручную, из поставки или из режима разработчика. */
+  installed: ExtensionInstallDto | null;
+  /** `true` у расширений с origin `user`: их можно удалить. */
+  removable: boolean;
+  /** Причина отзыва установленной версии в каталоге; `null` — не отозвана. Отозванное расширение в состоянии `disabled`, включить его нельзя. */
+  revoked: string | null;
+  /**
+   * Предупреждение об устаревании, действующее для установленной версии (по последнему известному
+   * индексу); `null` — расширение не устарело, скопировано вручную или индекса нет. Накладывает сервис
+   * `extensions.list`; это предупреждение, а не отзыв: состояние и политика не меняются.
+   */
+  deprecated: DeprecationDto | null;
+}
+/** Зависимость расширения (`dependencies` манифеста): `range` — диапазон версий, `null` — любая. */
+interface ExtensionDependencyDto {
+  id: string;
+  range: string | null;
+}
+/** Альтернатива устаревшему расширению; `name` берётся из индекса каталога. */
+interface DeprecationAlternativeDto {
+  id: string;
+  /** Название записи каталога; `null` — такой записи в индексе нет. */
+  name: string | null;
+}
+/** Расширение помечено устаревшим в каталоге (`deprecated.json`). */
+interface DeprecationDto {
+  /** Диапазон версий, на которые распространяется пометка; `null` — на все. */
+  versions: string | null;
+  /** Причина, 1–200 символов, на английском. */
+  reason: string;
+  /** До 3 альтернатив. */
+  alternatives: DeprecationAlternativeDto[];
+}
+/** Метаданные установки из каталога (файл `.dolphy-install.json` в каталоге расширения). */
+interface ExtensionInstallDto {
+  catalogUrl: string;
+  version: string;
+  /** ISO-время установки. */
+  installedAt: string;
+}
+/** Id серверных вкладов расширения (то, что оно зарегистрировало вызовом `server`). */
+interface ExtensionContributesDto {
+  exerciseTypes: string[];
+  gradePolicies: string[];
+  /** Id настроек (`server.registerSettings`). */
+  settings: string[];
+  /** Имена событий обучения (`server.on`). */
+  events: string[];
+  /** Id команд (`server.registerCommand`). */
+  commands: string[];
+  /** Id расписаний (`server.schedule`). */
+  schedules: string[];
+  /** Id импортёров (`server.registerImporter`). */
+  importers: string[];
+  /** Id экспортёров (`server.registerExporter`). */
+  exporters: string[];
+}
+/**
+ * Привязка команды расширения (`keybindings` регистрации команды). `mac`/`windows`/`linux`
+ * заменяют `key` на своей платформе (`null` — `key`); `when` — условие
+ * (`null` — без условия).
+ */
+interface ExtensionKeybindingDto {
+  key: string;
+  mac: string | null;
+  windows: string | null;
+  linux: string | null;
+  when: string | null;
+}
+/** Серверная команда расширения (`server.registerCommand`). */
+interface CommandContributionDto {
+  /** Id в пространстве расширения. */
+  id: string;
+  extensionId: string;
+  /** Название в палитре. */
+  title: LocalizedTextDto;
+  description: LocalizedTextDto | null;
+  category: LocalizedTextDto | null;
+  /** Привязки команды (до 4); `[]` — нет. Привязывают только эту команду. */
+  keybindings: ExtensionKeybindingDto[];
+  /** `false` скрывает команду из палитры: её вызывает только панель. */
+  palette: boolean;
+  /**
+   * Условие видимости (`parseWhen` из `@dolphy-app/extension-api`), `null` — всегда.
+   * Пока оно ложно, команды нет в палитре и она не выполняется сочетанием;
+   * расширению она по-прежнему доступна.
+   */
+  when: string | null;
+  /** Имя значка из закрытого списка `EXTENSION_ICONS` (умолчание `puzzle`); окно рисует свой символ, подпись декоративна. */
+  icon: string;
+}
+/** Расписание расширения (`server.schedule`): когда приложение запускает обработчик. */
+interface ScheduleContributionDto {
+  id: string;
+  extensionId: string;
+  /** `daily` — раз в сутки в `at`, `hourly` — в начале каждого часа; по местному времени. */
+  every: 'daily' | 'hourly';
+  /** `HH:MM` у `daily`; `null` у `hourly`. */
+  at: string | null;
+}
+/** Импортёр расширения (`server.registerImporter`): файл пользователя → каталог курса. */
+interface ImporterContributionDto {
+  id: string;
+  extensionId: string;
+  /** Название в палитре и карточке «Библиотеки». */
+  title: LocalizedTextDto;
+  /** Допустимые расширения файла в нижнем регистре (`.csv`), от 1 до 8; фильтр системного диалога. */
+  accept: string[];
+  /** `text` — обработчик получает файл строкой UTF-8, `bytes` — байтами. */
+  input: 'text' | 'bytes';
+}
+/** Экспортёр расширения (`server.registerExporter`): курс или прогресс → файл пользователя. */
+interface ExporterContributionDto {
+  id: string;
+  extensionId: string;
+  /** Название в палитре и карточке «Библиотеки». */
+  title: LocalizedTextDto;
+  /** `course` — снимок выбранного курса; `progress` — статистика через `server.stats`. */
+  scope: 'course' | 'progress';
+}
+/** Что вернул обработчик команды; окно исполняет `notify` и `openPanel` само. */
+type CommandResultDto = {
+  kind: 'none';
+} | {
+  kind: 'notify';
+  text: string;
+} | {
+  kind: 'openPanel';
+  panelId: string;
+  props?: JsonValue;
+} | {
+  kind: 'data';
+  value: JsonValue;
+};
+/** Parameters of `extensions.invokeRpc`. */
+interface ExtensionRpcRequest {
+  extensionId: string;
+  /** The name of the contract (`RPC_NAME_PATTERN` of the extension API). */
+  name: string;
+  /** A JSON value; at most `MAX_ANSWER_CHARS` characters of `JSON.stringify(input)`. */
+  input: unknown;
+}
+/** Файл, который пользователь выбрал для импортёра: имя без каталога и содержимое по `input` импортёра. */
+type ImportFileDto = {
+  name: string;
+  text: string;
+} | {
+  name: string;
+  bytes: Uint8Array;
+};
+/** Результат `extensions.runImporter`: сводка присланного дерева после проверки компилятором курсов. */
+interface ImportPreviewDto {
+  /** Для `commitImport` и `discardImport`; `null` — в дереве есть ошибки или нет ни одного курса: ничего не ожидает, на диске ничего нет. */
+  importId: string | null;
+  extensionId: string;
+  importerId: string;
+  /** Каталог курса от корня библиотеки: `imported/<id расширения>-<имя файла латиницей>`. */
+  path: string;
+  /** Каталог уже есть (повторный импорт того же файла): `commitImport` заменит его. */
+  replaces: boolean;
+  /** Файлов в присланном дереве. */
+  files: number;
+  counts: {
+    courses: number;
+    lessons: number;
+    exercises: number;
+  };
+  /** Все диагностики дерева, а не только вошедшие в `diagnostics`. */
+  summary: DiagnosticSummary;
+  /** Ошибки, затем предупреждения, не более 50, без `info`; пути — от каталога курса. */
+  diagnostics: Diagnostic[];
+}
+/** Результат `extensions.commitImport`. */
+interface CommitImportResultDto {
+  /** Каталог курса от корня библиотеки. */
+  path: string;
+  /** Прежний каталог был заменён. */
+  replaced: boolean;
+  /** Курсы каталога; после `commitImport` они в библиотеке. */
+  courseIds: UnitId[];
+}
+/** Что экспортировать: курс (снимок собирает движок) или прогресс (обработчик читает `server.stats`). */
+type ExportRequestDto = {
+  scope: 'course';
+  courseId: UnitId;
+} | {
+  scope: 'progress';
+};
+/** Файл, который вернул экспортёр; имя без разделителей пути, размер проверен. */
+type ExportFileDto = {
+  filename: string;
+  text: string;
+} | {
+  filename: string;
+  bytes: Uint8Array;
+};
+/** Вид задания расширения (`server.registerExerciseType`). */
+interface ExerciseTypeContributionDto {
+  type: string;
+  extensionId: string;
+  /** Название для чипа вклада; `null` — показывается id. */
+  title: LocalizedTextDto | null;
+}
+interface GradePolicyInfoDto {
+  id: string;
+  /** `null` у встроенного правила. */
+  extensionId: string | null;
+  /** `null` у встроенного правила: название переводит окно. */
+  label: LocalizedTextDto | null;
+}
+/**
+ * Клиентская часть включённого расширения: окно импортирует `url`, вызывает
+ * `client(c)` и держит свой реестр вкладов (панели, места, виды ответа,
+ * рендереры markdown, темы, клиентские команды); в движок они не попадают.
+ */
+interface ExtensionClientDto {
+  extensionId: string;
+  /** `dolphy-ext://<extensionId>/<client>` — собранный `client.mjs`. */
+  url: string;
+  origin: ExtensionOriginDto;
+  /** Отпечаток файлов расширения; у расширений из поставки — пустая строка. У `dev` меняется при правке: окно загружает клиентскую часть заново. */
+  revision: string;
+}
+interface ContributionsDto {
+  /**
+   * Поколение набора вкладов: растёт при каждом применении расширений и равно
+   * `generation` последнего события `contributions-changed`. Ответ с меньшим
+   * поколением, чем уже виденное в событии, устарел. Отсчёт начинается заново
+   * при каждом запуске движка.
+   */
+  generation: number;
+  /** Включённые расширения с клиентской частью (`client.mjs`). */
+  clients: ExtensionClientDto[];
+  exerciseTypes: ExerciseTypeContributionDto[];
+  gradePolicies: GradePolicyInfoDto[];
+  /** Определения настроек включённых расширений. */
+  settings: ExtensionSettingDefDto[];
+  /** Серверные команды включённых расширений. */
+  commands: CommandContributionDto[];
+  /** Расписания включённых расширений. */
+  schedules: ScheduleContributionDto[];
+  /** Импортёры включённых расширений. */
+  importers: ImporterContributionDto[];
+  /** Экспортёры включённых расширений. */
+  exporters: ExporterContributionDto[];
+}
+interface ExtensionSettingBaseDto {
+  /** Равен id расширения или начинается с `<id расширения>.`. */
+  id: string;
+  extensionId: string;
+  /** Подпись поля в диалоге настроек. */
+  label: LocalizedTextDto;
+  description: LocalizedTextDto | null;
+  /** Заголовок раздела формы; `null` — настройка в первом разделе без заголовка. */
+  group: LocalizedTextDto | null;
+  /** Ключ сортировки формы, целое 0–1000; при равных — порядок объявления. */
+  order: number;
+  /** Поле скрыто, пока значение настройки `setting` (того же расширения, не `list`) не равно `equals`; скрытое значение сохраняется. `null` — поле видно всегда. */
+  visibleWhen: SettingVisibleWhenDto | null;
+}
+/** Условие показа поля формы настроек. */
+interface SettingVisibleWhenDto {
+  setting: string;
+  equals: boolean | string | number;
+}
+interface BooleanSettingDefDto extends ExtensionSettingBaseDto {
+  type: 'boolean';
+  default: boolean;
+}
+interface StringSettingDefDto extends ExtensionSettingBaseDto {
+  type: 'string';
+  default: string;
+  /** Длина в кодовых единицах UTF-16; `null` — без ограничения. */
+  maxLength: number | null;
+}
+/** Многострочная строка. */
+interface TextSettingDefDto extends ExtensionSettingBaseDto {
+  type: 'text';
+  default: string;
+  /** Длина в кодовых единицах UTF-16; `null` — до 10 000. */
+  maxLength: number | null;
+}
+/** Цвет `#rrggbb`; значение хранится в нижнем регистре. */
+interface ColorSettingDefDto extends ExtensionSettingBaseDto {
+  type: 'color';
+  default: string;
+}
+/** Список строк. */
+interface ListSettingDefDto extends ExtensionSettingBaseDto {
+  type: 'list';
+  default: string[];
+  /** Наибольшее число элементов, 1–50. */
+  maxItems: number;
+  /** Наибольшая длина элемента в кодовых единицах UTF-16, 1–200. */
+  itemMaxLength: number;
+}
+interface NumberSettingDefDto extends ExtensionSettingBaseDto {
+  type: 'number';
+  default: number;
+  min: number | null;
+  max: number | null;
+  integer: boolean;
+}
+interface EnumSettingOptionDto {
+  value: string;
+  label: LocalizedTextDto;
+}
+interface EnumSettingDefDto extends ExtensionSettingBaseDto {
+  type: 'enum';
+  default: string;
+  options: EnumSettingOptionDto[];
+}
+/** Настройка расширения, которую пользователь меняет в «Настройки → Расширения». */
+type ExtensionSettingDefDto = BooleanSettingDefDto | StringSettingDefDto | TextSettingDefDto | ColorSettingDefDto | ListSettingDefDto | NumberSettingDefDto | EnumSettingDefDto;
+/** Действующие значения настроек расширения: по `id` каждого определения; сохранённое или `default`. */
+type ExtensionSettingValuesDto = Record<string, JsonValue>;
+/** Занятое место данных расширения (хранилище кода, значения настроек и секреты считаются отдельно; у секретов байты — шифртекст). */
+interface ExtensionDataUsageDto {
+  storage: {
+    keys: number;
+    bytes: number;
+  };
+  settings: {
+    keys: number;
+    bytes: number;
+  };
+  secrets: {
+    keys: number;
+    bytes: number;
+  };
+}
+/** Чем безопасный режим задан при запуске: флагом `--safe-mode` или переменной `DOLPHY_SAFE_MODE`. */
+type SafeModeSource = 'flag' | 'env';
+/** Настройки расширений; хранятся вместе с остальными настройками в `engine.db`. */
+interface ExtensionSettingsDto {
+  /** Отключённые расширения (по id), отсортированы, без повторов. */
+  disabled: string[];
+  /** Проверять обновления расширений из каталога при запуске. По умолчанию включено. */
+  checkUpdates: boolean;
+  /**
+   * Безопасный режим: расширения не из поставки отключены (диагностика
+   * `safe-mode`), их код не запускается. Расширения из поставки работают.
+   * По умолчанию выключено. Флаг запуска включает режим независимо от настройки.
+   */
+  safeMode: boolean;
+  /**
+   * Расширения с выключенными системными уведомлениями (по id), отсортированы,
+   * без повторов: `server.notifications.show` у них даёт `false`. По умолчанию
+   * пусто (уведомления включены).
+   */
+  notificationsOff: string[];
+  /**
+   * Свой адрес каталога расширений (канонический `URL.href`); `null` — адрес
+   * по умолчанию (адрес, равный умолчанию, тоже хранится как `null`).
+   * Нечитаемое сохранённое значение читается как `null`.
+   */
+  catalogUrl: string | null;
+  /**
+   * Расширения с выключенными расписаниями (по id), отсортированы, без
+   * повторов: их `server.schedule` не срабатывает. По умолчанию пусто
+   * (расписания включены).
+   */
+  schedulesOff: string[];
+}
+/** Откуда взят действующий адрес каталога: умолчание, настройка или `DOLPHY_EXTENSION_CATALOG_URL` (только несобранное приложение). */
+type CatalogSourceOrigin = 'default' | 'setting' | 'env';
+/** Действующий адрес каталога расширений (`extensions.catalogSource`). */
+interface CatalogSourceDto {
+  /** Адрес, из которого читается каталог: идентичность каталога в `ExtensionInstallDto.catalogUrl`. */
+  url: string;
+  /** Адрес по умолчанию (официальный каталог). */
+  default: string;
+  origin: CatalogSourceOrigin;
+}
+/** Состояние процесса хоста расширений: `gave-up` — после повторных сбоев перезапуск прекращён до `restartHost()`. */
+type ExtensionHostStatusDto = 'running' | 'restarting' | 'gave-up';
+/** Сбой расширения; `reason` — причина (`handler-failed`, `timeout`, `invalid-result`, `activation-failed`), `message` — текст сбоя. */
+interface ExtensionFailureDto {
+  at: EpochMs;
+  reason: string;
+  message: string;
+}
+/** Здоровье одного расширения с запуска приложения (в памяти, не сохраняется; сбрасывается при смене файлов расширения). */
+interface ExtensionHealthDto {
+  id: string;
+  /** Сбоев команд, событий и видов заданий. Убийства процесса и приостановка — состояние, а не сбой. */
+  failures: number;
+  lastFailure: ExtensionFailureDto | null;
+  /** Длительность последней успешной активации; `null` — расширение не активировалось. */
+  lastActivationMs: number | null;
+  /** Ограниченный процесс приостановлен за цикл падений до этого времени; `null` — не приостановлен. */
+  suppressedUntil: EpochMs | null;
+}
+/** Безопасный режим: `active` = `persisted` или `forcedBy !== null`. */
+interface SafeModeStatusDto {
+  active: boolean;
+  /** Значение настройки `safeMode`. */
+  persisted: boolean;
+  forcedBy: SafeModeSource | null;
+}
+/** Уровни записи журнала от подробного к важному. */
+declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+type LogLevelDto = (typeof LOG_LEVELS)[number];
+/** Запись файлового журнала. */
+interface ExtensionLogEntryDto {
+  at: EpochMs;
+  level: LogLevelDto;
+  /** Кто написал: `main`, `engine` или `ext-host`. */
+  source: string;
+  message: string;
+  /** Расширение, к которому относится запись; `null` — запись самого приложения. */
+  extensionId: string | null;
+  /** Остальные поля записи одной JSON-строкой (обрезаются до 4096 знаков); `null` — полей нет. */
+  details: string | null;
+}
+/** Параметры `extensions.readLogs`. */
+interface ReadLogsOptions {
+  /** Только записи этого расширения. */
+  extensionId?: string;
+  /** Записи не ниже этого уровня; по умолчанию все. */
+  minLevel?: LogLevelDto;
+  /** Сколько последних записей вернуть, 1…`MAX_LOG_ENTRIES`; по умолчанию `MAX_LOG_ENTRIES`. */
+  limit?: number;
+}
+interface ExtensionsDiagnosticsDto {
+  host: ExtensionHostStatusDto;
+  safeMode: SafeModeStatusDto;
+  /** Запись для каждого расширения из `list()` (у не сбоивших — нули). */
+  extensions: ExtensionHealthDto[];
+}
+interface ExtensionsService {
+  list(): Promise<ExtensionInfoDto[]>;
+  getSettings(): Promise<ExtensionSettingsDto>;
+  /** `NOT_FOUND` — нет такого расширения; `INVALID_ARGUMENT` `{reason:'bundled'}` — расширение из поставки. */
+  setEnabled(id: string, enabled: boolean): Promise<ExtensionSettingsDto>;
+  /**
+   * Включает и выключает системные уведомления расширения (`notificationsOff`);
+   * не перезапускает расширение. `NOT_FOUND` — нет такого расширения;
+   * `INVALID_ARGUMENT` `{reason:'bundled'}` — расширение из поставки не
+   * настраивается; не булево значение — `INVALID_ARGUMENT`.
+   */
+  setNotificationsEnabled(id: string, enabled: boolean): Promise<ExtensionSettingsDto>;
+  /**
+   * Включает и выключает расписания расширения (`schedulesOff`); не
+   * перезапускает расширение. `NOT_FOUND` — нет такого расширения;
+   * `INVALID_ARGUMENT` `{reason:'bundled'}` — расширение из поставки не
+   * настраивается; не булево значение — `INVALID_ARGUMENT`.
+   */
+  setSchedulesEnabled(id: string, enabled: boolean): Promise<ExtensionSettingsDto>;
+  /** Вклады загруженных расширений для окна (только чтение). */
+  contributions(): Promise<ContributionsDto>;
+  /**
+   * Каталог расширений. `refresh` — запросить индекс у сервера (иначе — кэш,
+   * если он свежий). Нет сети: последний кэш и `stale: true`; кэша нет —
+   * `CATALOG_UNAVAILABLE`.
+   */
+  catalog(options?: {
+    refresh?: boolean;
+  }): Promise<CatalogDto>;
+  /**
+   * Устанавливает (или обновляет) расширение из каталога; `version` — точная
+   * версия, иначе новейшая совместимая. `NOT_FOUND` — нет в каталоге;
+   * `EXTENSION_INSTALL_FAILED` с `details.reason`:
+   * `incompatible` | `network` | `integrity` | `limits` | `invalid` | `conflict`.
+   * Установленное действует сразу: перед ответом движок и хост расширений
+   * применили набор, окно получило событие `contributions-changed`.
+   */
+  install(id: string, version?: string): Promise<InstallResultDto>;
+  /**
+   * Удаляет расширение с origin `user`. `removeData` — удалить и данные
+   * расширения (по умолчанию остаются). `NOT_FOUND`; `INVALID_ARGUMENT`
+   * `{reason:'not-removable'}`.
+   */
+  uninstall(id: string, options?: {
+    removeData?: boolean;
+  }): Promise<void>;
+  /** Доступные обновления установленных из каталога расширений (по последнему известному индексу). */
+  updates(): Promise<ExtensionUpdateDto[]>;
+  /**
+   * README и журнал изменений. Без `version` — установленной версии (из каталога расширения, без сети),
+   * у не установленного — новейшей показанной версии каталога; с `version` — этой версии (установленной
+   * или из каталога; файлы каталога проверяются по размеру и `sha256` и кэшируются на диске).
+   * `NOT_FOUND` — нет такого расширения или версии; `EXTENSION_INSTALL_FAILED`
+   * (`details.reason` `network` | `integrity` | `limits`) — файл недоступен; `CATALOG_UNAVAILABLE` — индекса нет.
+   */
+  docs(id: string, options?: {
+    version?: string;
+  }): Promise<ExtensionDocsDto>;
+  /**
+   * Картинка README как `data:image/png|webp|jpeg;base64,…`: файл `png`/`webp`/`jpg`/`jpeg` до 256 КиБ из
+   * файлов этой версии. `NOT_FOUND` — расширения, версии или файла нет; `INVALID_ARGUMENT` — путь,
+   * тип или размер недопустимы.
+   */
+  docImage(id: string, version: string, path: string): Promise<string>;
+  setCheckUpdates(enabled: boolean): Promise<ExtensionSettingsDto>;
+  /**
+   * Меняет адрес каталога расширений; `null` — вернуть умолчание. Адрес: `https:`
+   * (или `http:` на loopback: `localhost`, `127.0.0.0/8`, `[::1]`), до 2048 знаков,
+   * без логина и фрагмента, путь оканчивается на `.json`; сохраняется как `URL.href`,
+   * равный умолчанию — как `null`. Действует сразу: установщик переключается,
+   * набор расширений применяется заново (отзыв и устаревание берутся только из
+   * нового каталога), метка проверки обновлений сбрасывается и проверка идёт заново,
+   * окно получает `extensions-changed`. Установленное из прежнего каталога
+   * остаётся (`.dolphy-install.json` не меняется). `INVALID_ARGUMENT` с
+   * `details.reason` (`CatalogUrlRejection`); `env` — адрес задан
+   * `DOLPHY_EXTENSION_CATALOG_URL`, настройка не меняется.
+   */
+  setCatalogUrl(url: string | null): Promise<ExtensionSettingsDto>;
+  /** Действующий адрес каталога, умолчание и источник значения. */
+  catalogSource(): Promise<CatalogSourceDto>;
+  /**
+   * Включает и выключает безопасный режим (настройка `safeMode`); действует
+   * сразу, без перезапуска. Не булево значение — `INVALID_ARGUMENT`.
+   */
+  setSafeMode(enabled: boolean): Promise<ExtensionSettingsDto>;
+  /** Здоровье расширений, состояние хоста расширений и безопасного режима. */
+  diagnostics(): Promise<ExtensionsDiagnosticsDto>;
+  /**
+   * Запускает хост расширений заново, сбрасывает счётчик его падений (после
+   * `gave-up` вернуть расширениям работу без перезапуска приложения).
+   */
+  restartHost(): Promise<void>;
+  /**
+   * Последние записи файлового журнала, самые новые последними. Читаются все
+   * файлы журнала от новых к старым; нечитаемые строки пропускаются. Неверные
+   * `limit`, `minLevel` или `extensionId` — `INVALID_ARGUMENT`.
+   */
+  readLogs(options?: ReadLogsOptions): Promise<ExtensionLogEntryDto[]>;
+  /**
+   * Действующие значения настроек расширения (определения — в
+   * `contributions().settings`). `NOT_FOUND` — расширения нет;
+   * `INVALID_ARGUMENT` `{reason:'disabled'}` — расширение отключено.
+   */
+  getSettingValues(id: string): Promise<ExtensionSettingValuesDto>;
+  /**
+   * Меняет одно значение; проверяет тип, границы, формат цвета, размер списка и `options` по определению; цвет сохраняется в нижнем регистре.
+   * Неизвестный `settingId` и неверное значение — `INVALID_ARGUMENT`
+   * (`details.reason`: `unknown-setting` | `type` | `range` | `integer` |
+   * `max-length` | `option` | `format` | `max-items`). Расширение и окно узнают об изменении без перезапуска.
+   */
+  setSettingValue(id: string, settingId: string, value: JsonValue): Promise<ExtensionSettingValuesDto>;
+  /** Возвращает значения по умолчанию (удаляет сохранённые). */
+  resetSettingValues(id: string): Promise<ExtensionSettingValuesDto>;
+  /** Сколько места занимают данные расширения; работает и для удалённого расширения, чьи данные остались. */
+  dataUsage(id: string): Promise<ExtensionDataUsageDto>;
+  /** Стирает хранилище и значения настроек; работающее расширение видит пустое хранилище и значения по умолчанию. */
+  clearData(id: string): Promise<void>;
+  /**
+   * Выполняет объявленную команду расширения (код расширения; первый вызов
+   * лениво его активирует). Вызов не занимает очередь команд движка.
+   * `INVALID_ARGUMENT` — неверный `extensionId`/`commandId` или аргументы длиннее
+   * `MAX_ANSWER_CHARS` (`details.reason`: `args-too-large`). Всё остальное —
+   * `EXTENSION_COMMAND_FAILED` с `details` `{ extensionId, commandId, reason }`
+   * (`ExtensionCommandFailureReason`): расширения или объявленной команды нет —
+   * `unknown-command`, расширение отключено — `disabled`, `timeout` и
+   * `host-down` допускают повтор.
+   */
+  invokeCommand(extensionId: string, commandId: string, args?: JsonValue): Promise<CommandResultDto>;
+  /**
+   * Calls a handler the server part of an extension registered with
+   * `server.handle` (first call activates the extension lazily). The input is
+   * validated against the input schema of the contract on the server, the
+   * result against the output schema. The call does not occupy the engine
+   * command queue. `INVALID_ARGUMENT` — a malformed `extensionId` or `name`,
+   * or an input longer than `MAX_ANSWER_CHARS` (`details.reason`:
+   * `args-too-large`). Everything else is `EXTENSION_RPC_FAILED` with
+   * `details` `{ extensionId, name, reason }` (`ExtensionRpcFailureReason`):
+   * a missing extension or handler — `unknown-rpc`, a disabled extension —
+   * `disabled`, an exception of the handler — `handler-failed` with the
+   * message of the exception; `timeout` and `host-down` allow a retry.
+   */
+  invokeRpc(params: ExtensionRpcRequest): Promise<unknown>;
+  /**
+   * Запускает объявленный импортёр на файле, который выбрал пользователь:
+   * присланное расширением дерево курса проверяется компилятором курсов во
+   * временном каталоге, на диск библиотеки ничего не попадает. Ожидающих
+   * импортов не более 4, каждый живёт 10 минут и пропадает вместе с движком.
+   * Вызов не занимает очередь команд. `INVALID_ARGUMENT` — неверные id, имя
+   * файла (не имя, а путь) или форма файла не по `input` импортёра.
+   * `EXTENSION_TRANSFER_FAILED` с `details` `{ extensionId, id, kind: 'import',
+   * reason }` (`ExtensionTransferFailureReason`): `unknown-importer`,
+   * `disabled`, `too-large` (файл больше `MAX_EXTENSION_TRANSFER_BYTES`),
+   * остальное — как в хосте; `timeout` и `host-down` допускают повтор.
+   */
+  runImporter(extensionId: string, importerId: string, file: ImportFileDto): Promise<ImportPreviewDto>;
+  /**
+   * Кладёт ожидающий импорт в библиотеку: заменяет каталог `imported/<имя>` и
+   * перезагружает библиотеку; курс виден без перезапуска. Библиотека отвергла
+   * результат — каталог откатывается, прежняя библиотека остаётся, ошибка
+   * `EXTENSION_TRANSFER_FAILED` с `reason: 'reload-rejected'` и `details`
+   * `summary` и `diagnostics`. Нет такого ожидающего импорта (не было,
+   * истёк, уже применён или отменён) — `NOT_FOUND`. Идёт в очереди команд.
+   */
+  commitImport(importId: string): Promise<CommitImportResultDto>;
+  /** Отменяет ожидающий импорт и удаляет его временный каталог; `false`, если такого не было. Идемпотентна. */
+  discardImport(importId: string): Promise<boolean>;
+  /**
+   * Запускает объявленный экспортёр. Для `scope: 'course'` движок читает
+   * текстовые файлы каталога курса (до `MAX_EXTENSION_TRANSFER_BYTES`) и
+   * передаёт их обработчику; для `progress` обработчик читает `server.stats`.
+   * Область запроса должна совпасть с областью экспортёра (иначе
+   * `INVALID_ARGUMENT`), курса нет — `NOT_FOUND`. Вызов не занимает очередь
+   * команд. Ошибки — как у `runImporter` с `kind: 'export'` и
+   * `unknown-exporter`; снимок курса больше потолка — `too-large`.
+   */
+  runExporter(extensionId: string, exporterId: string, request: ExportRequestDto): Promise<ExportFileDto>;
+}
+type CatalogStatusDto = 'available' | 'installed' | 'update' | 'incompatible';
+interface CatalogVersionDto {
+  version: string;
+  /** Зависимости версии; установка их не ставит и не блокируется. */
+  dependencies: ExtensionDependencyDto[];
+  /** ISO-время публикации. */
+  publishedAt: string;
+  /** Суммарный размер файлов, байты. */
+  size: number;
+  minAppVersion: string | null;
+}
+/** Версия в списке версий записи каталога (не больше 5, новейшие первыми). */
+interface CatalogListedVersionDto extends CatalogVersionDto {
+  /** `true` — версию можно установить на этом приложении и платформе. */
+  compatible: boolean;
+  /** Почему нельзя установить; `null` у совместимой. */
+  incompatible: {
+    reason: CatalogIncompatibleDto['reason'];
+    detail: string;
+  } | null;
+  /** В версии есть `CHANGELOG.md`. */
+  hasChangelog: boolean;
+}
+interface CatalogIncompatibleDto {
+  reason: 'platform' | 'api' | 'app' | 'revoked';
+  /** Человекочитаемая причина на английском (`requires app >= 1.2.0`). */
+  detail: string;
+  /** Ближайшая более старая совместимая версия; `null` — нет. */
+  fallback: CatalogVersionDto | null;
+}
+interface CatalogEntryDto {
+  id: string;
+  name: string;
+  description: string;
+  author: string;
+  /** Адрес исходников (страница в репозитории каталога). */
+  source: string;
+  platforms: string[];
+  /** Значок показанной версии как `data:image/png|webp;base64,…`; `null` — значка нет (или каталог старого формата). */
+  icon: string | null;
+  /** Теги показанной версии из записи индекса; `[]` — нет. */
+  tags: string[];
+  status: CatalogStatusDto;
+  /** Версия, установленная из каталога; `null` — не установлено (или скопировано вручную). */
+  installedVersion: string | null;
+  /** Версия, которая будет установлена (новейшая совместимая); `null` у несовместимых. */
+  latest: CatalogVersionDto | null;
+  incompatible: CatalogIncompatibleDto | null;
+  /** Версии записи индекса (до 5, новейшие первыми). */
+  versions: CatalogListedVersionDto[];
+  /** Пометка «устарело», действующая для показанной версии (`latest`, у несовместимых — новейшая); `null` — нет. */
+  deprecated: DeprecationDto | null;
+  /**
+   * `true` — расширение с этим id уже есть, но установлено не из этого каталога (скопировано вручную,
+   * из режима разработчика, из поставки или из другого каталога): установка невозможна без удаления прежнего.
+   */
+  elsewhere: boolean;
+}
+interface CatalogDto {
+  entries: CatalogEntryDto[];
+  /** ISO-время получения индекса; `null` — индекса нет. */
+  fetchedAt: string | null;
+  /** Показан кэш, потому что свежий индекс получить не удалось. */
+  stale: boolean;
+  /** Причина, по которой не удалось обновить индекс; `null` — без ошибок. */
+  error: string | null;
+}
+interface ExtensionUpdateDto {
+  id: string;
+  name: string;
+  installed: string;
+  available: CatalogVersionDto;
+}
+/** Описание расширения: README и журнал изменений одной версии. */
+interface ExtensionDocsDto {
+  /** Версия, к которой относятся тексты. */
+  version: string;
+  /** Содержимое `README.md` (первые 64 КиБ); `null` — файла нет. */
+  readme: string | null;
+  /** Содержимое `CHANGELOG.md` версии; `null` — файла нет. */
+  changelog: string | null;
+  /** Любой из текстов обрезан до 64 КиБ. */
+  truncated: boolean;
+  /**
+   * Откуда тексты: `installed` — каталог установленного расширения; `catalog` — каталог (скачаны или
+   * уже лежали в дисковом кэше); `cache` — дисковый кэш, потому что до каталога не дозвониться (индекс устарел).
+   */
+  source: 'installed' | 'catalog' | 'cache';
+}
+interface InstallResultDto {
+  id: string;
+  version: string;
+  /** Прежняя версия из каталога; `null` — новая установка. */
+  previousVersion: string | null;
+}
+interface LearningEngine {
+  readonly library: LibraryService;
+  readonly repositories: RepositoriesService;
+  readonly practice: PracticeService;
+  readonly curation: CurationService;
+  readonly settings: SettingsService;
+  readonly sync: SyncService;
+  readonly plan: PlanService;
+  readonly placement: PlacementService;
+  readonly remediation: RemediationService;
+  readonly extensions: ExtensionsService;
+  diagnostics(): Promise<EngineDiagnosticsDto>;
+  /** In-process. По RPC — сообщения `events.subscribe` / `events.unsubscribe` и push `EngineEvent`. */
+  subscribe(listener: (event: EngineEvent) => void): () => void;
+  close(): Promise<void>;
+}
+/**
+ * What an extension gets as `ctx.engine` on the server and `useEngine()` in a
+ * component: every method of `LearningEngine` including `subscribe`, but not
+ * `close`. Over the wire `subscribe` is the `events.subscribe` /
+ * `events.unsubscribe` messages of `RPC_CONTROL`.
+ */
+type ExtensionEngine = Omit<LearningEngine, 'close'>;
+//#endregion
+export { ExtensionEngine as t };