@alizadefaig/pos-server 1.2.26 → 1.2.28

package/app/sync/index.js

@@ -0,0 +1,1644 @@
+const axios = require('axios');
+const kv = require('./kv');
+const config = require('./config');
+const {getStore} = require('./store');
+const {CloudClient, CloudRequestError, normalizeApiUrl} = require('./cloud');
+const {CloudSignal} = require('./signal');
+const {MasterBridge} = require('./bridge');
+const {lanHeaders} = require('./lan');
+const discovery = require('./discovery');
+const lanDevices = require('./lanDevices');
+const lanFront = require('./lanFront');
+const {getConfig} = require('../config');
+const mirror = require('./mirror');
+const snapshot = require('./snapshot');
+const {pushBatch, pendingCount, foreignPending} = require('./push');
+const reconcile = require('./reconcile');
+const monitor = require('../monitor');
+const {HttpError} = require('../core/errors');
+const {unlockThrottle, findUnlockUser, throttleKey} = require('../core/support/unlock');
+const {version: PACKAGE_VERSION} = require('../../package.json');
+
+/**
+ * Оркестратор синка локального Node с облаком (OFFLINE-FIRST-PLAN §11, модель F).
+ *
+ * Облако — основная система. Локальный Node держит зеркало (справочники + чеки) и решает,
+ * куда ходить фронту: фронт сам сеть не проверяет, а читает `mode` из GET /local/status.
+ *
+ *   cloud      — фронт работает с облаком как сегодня; Node в фоне тянет зеркало;
+ *   offline    — облака нет: фронт переключён на локальный Node, правки копятся в sync_dirty;
+ *   recovering — связь вернулась, офлайн-правки ещё не досланы: фронт остаётся на локальном
+ *                Node, пока push не опустошит очередь, — иначе он увидел бы в облаке чек без
+ *                своих офлайн-позиций.
+ *
+ * Связь меряется гистерезисом: failuresToOffline провалов подряд → offline,
+ * successesToOnline успехов подряд → online. Одиночный таймаут режим не дёргает.
+ *
+ * Всё выключено, пока нет OFFLINE_CORE + OFFLINE_SYNC + CORE_DB=sqlite (config.isSyncEnabled):
+ * mode() тогда null, и ядро ведёт себя как раньше.
+ *
+ * Модель M (§12) — поверх: режим заведения ведёт облако (companies.pos_mode, суперадминка), касса
+ * узнаёт его опросом sync.mode (заодно heartbeat) и сразу по сокет-событию pos:mode.
+ *
+ *   local    — эта касса — мастер заведения: истина чеков у неё, интернет не нужен. Клиенты облака
+ *              ходят к ней через облачный Node (master:request), выгрузка в облако авторитетна;
+ *   draining — заведение возвращается в онлайн: мастер досылает очередь, правок не принимает,
+ *              затем releaseMaster.
+ * Переход в local: заведение в to_local → касса выгружает недосланное, забирает облачную копию
+ * целиком и только после этого claimMaster. Пока идёт переход, облако правок не принимает
+ * (409 mode_switching), поэтому забранная копия полная.
+ */
+
+const state = {
+    started: false,
+    starting: null,
+    store: null,
+    session: null,
+    cloud: null,
+    signal: null,
+    bridge: null,
+    // автопоиск мастера в зале: finder — у ведомого с OFFLINE_MASTER_URL=auto, responder — у мастера
+    finder: null,
+    responder: null,
+    timer: null,
+    wakeTimer: null,
+    running: false,
+    rerun: false,
+
+    mode: 'cloud',
+    online: null,
+    fails: 0,
+    oks: 0,
+    lastOkAt: null,
+    lastError: null,
+
+    pending: 0,
+    foreignPending: [],
+    needSnapshot: true,
+    lastSnapshotTry: 0,
+    // снапшот по сигналу облака — не раньше этого момента (SNAPSHOT_SIGNAL_MIN_MS)
+    snapshotNotBefore: 0,
+    lastSnapshotOk: 0,
+    lastPullAt: 0,
+    pullRequested: false,
+    lastPushAt: null,
+    lastPushError: null,
+    batchSize: null,
+
+    // 'entity:id' → {version, attempts, reason}: запись, которую облако раз за разом не принимает
+    poison: new Map(),
+    conflicts: [],
+
+    master: {reachable: null, mode: null, checkedAt: null, error: null},
+
+    // модель M: режим заведения из sync.mode {company_id, state, master_terminal_id, epoch, enabled}
+    company: null,
+    modeRequested: true,
+    lastModePoll: 0,
+    lastModeError: null,
+    handover: {stage: null, epoch: null, error: null, at: null, lastTry: 0},
+    // чеки, которые облако просит перечитать (sync:pull)
+    pullIds: new Set(),
+
+    // выход терминала (logout): с какого момента облако на связи, а очередь ещё не пуста;
+    // идёт отзыв токена — возврат на кассу (resume) в это время невозможен
+    revokeWaitFrom: null,
+    revoking: false,
+
+    // сверка касса ↔ облако (reconcile.js): последний итог, расхождений подряд, сколько вылечено
+    reconcile: {
+        nextAt: 0, at: null, ok: null, streak: 0, local: null, cloud: null,
+        diff: null, truncated: false, healed: 0, error: null,
+    },
+};
+
+const SNAPSHOT_RETRY_MS = 60000;
+// Снапшот по сигналу облака (sync:snapshot) — не чаще: серия правок в бэк-офисе даёт один снапшот.
+const SNAPSHOT_SIGNAL_MIN_MS = 10000;
+const MAX_PUSH_ROUNDS = 20;
+const MAX_CONFLICTS_KEPT = 20;
+const HANDOVER_RETRY_MS = 10000;
+const MAX_HANDOVER_PULL_ROUNDS = 50;
+const PULL_IDS_CHUNK = 200;
+// выход терминала: отзыв токена не дольше этого (фронт ждёт ответ на /local/logout)
+const REVOKE_TIMEOUT_MS = 3000;
+// токенов прошлых сессий в очереди на отзыв
+const MAX_LOGOUT_QUEUE = 20;
+
+const COMPANY_STATES = new Set(['online', 'to_local', 'local', 'to_online']);
+const MASTER_STATES = new Set(['to_local', 'local', 'to_online']);
+// Режимы, в которых фронт работает с локальным Node (а не с облаком).
+const LOCAL_MODES = new Set(['offline', 'recovering', 'local', 'draining']);
+// Эти события облако кассе не ретранслирует (LocalModeMiddleware их пропускает), а если
+// пришли — не исполняем: вход по PIN и init терминала облака не должны зависеть от кассы.
+const RELAY_DENY = /^(app|auth|sync)\./;
+
+const nowIso = () => new Date().toISOString();
+
+const log = (...args) => console.log('[sync]', ...args);
+
+const isFollower = () => config.role() === 'follower';
+
+// ---------------------------------------------------------------- связь (гистерезис)
+
+const onLink = (ok, error = null) => {
+    const {failuresToOffline, successesToOnline} = config.limits();
+    if (ok) {
+        state.oks += 1;
+        state.fails = 0;
+        state.lastOkAt = nowIso();
+        if (state.online !== true && (state.online === null || state.oks >= successesToOnline)) {
+            if (state.online === false) {
+                log('cloud reachable again');
+            }
+            state.online = true;
+        }
+        return;
+    }
+    state.fails += 1;
+    state.oks = 0;
+    state.lastError = error;
+    if (state.online !== false && (state.online === null || state.fails >= failuresToOffline)) {
+        log(`cloud unreachable: ${error}`);
+        state.online = false;
+    }
+};
+
+// ---------------------------------------------------------------- режим
+
+const excludedKeys = () => {
+    const limit = config.limits().poisonAttempts;
+    const keys = new Set();
+    for (const [key, entry] of state.poison) {
+        if (entry.attempts >= limit) {
+            keys.add(key);
+        }
+    }
+    return keys;
+};
+
+const hasInit = () => Boolean(state.store && kv.get(state.store, 'snapshot_at'));
+
+/** Заведение сессии: push и счётчик очереди работают только с его записями (см. push.js). */
+const sessionCompanyId = () => (state.session ? state.session.company_id : null);
+
+const refreshPending = () => {
+    if (!state.store || isFollower()) {
+        state.pending = 0;
+        state.foreignPending = [];
+        return 0;
+    }
+    try {
+        state.pending = pendingCount(state.store, excludedKeys(), sessionCompanyId());
+        state.foreignPending = foreignPending(state.store, sessionCompanyId());
+    } catch (e) {
+        console.error('[sync] pending count failed:', e.message);
+    }
+    return state.pending;
+};
+
+const computeFollowerMode = () => {
+    const master = state.master;
+    if (master.reachable) {
+        // Мастер работает локально — идём за ним, даже если своя связь есть: иначе один чек
+        // правили бы в двух местах сразу.
+        if (LOCAL_MODES.has(master.mode)) {
+            return master.mode;
+        }
+        return state.online === false ? 'offline' : 'cloud';
+    }
+    // Мастера не видно: облако доступно — работаем с ним; нет и облака — работать не с чем,
+    // остаёмся на локальном Node, чтобы фронт показал внятную ошибку, а не висел.
+    return state.online === false ? 'offline' : 'cloud';
+};
+
+/** Эта касса — мастер заведения (модель M): облако назначило её, эпоха своя. */
+const isMasterNow = () => {
+    const company = state.company;
+    const session = state.session;
+    return Boolean(
+        company && session && company.enabled
+        && company.company_id === session.company_id
+        && MASTER_STATES.has(company.state)
+        && company.master_terminal_id === session.terminal_id
+    );
+};
+
+const computeMode = () => {
+    if (!config.isSyncEnabled() || !state.session || !hasInit()) {
+        return 'cloud';
+    }
+    if (isFollower()) {
+        return computeFollowerMode();
+    }
+    const pending = refreshPending();
+    if (isMasterNow()) {
+        // Истина у кассы — связь с облаком для работы не нужна.
+        if (state.company.state === 'local') {
+            return 'local';
+        }
+        if (state.company.state === 'to_online') {
+            return 'draining';
+        }
+        // to_local: облако ещё истина, пока касса его не забрала — дальше как модель F.
+    }
+    if (state.online === false) {
+        return 'offline';
+    }
+    if (state.online === null) {
+        // Старт до первой проверки: недосланные правки есть — фронт сразу на локальный Node.
+        return pending > 0 ? 'recovering' : 'cloud';
+    }
+    // Бывший мастер (сменили мастера, force_online) досылает свою очередь как после обрыва:
+    // фронт остаётся на локальном Node, пока правки не уедут.
+    if (LOCAL_MODES.has(state.mode) && pending > 0) {
+        return 'recovering';
+    }
+    // В облачном режиме грязные записи тоже бывают (запрос, пришедший на локальный Node
+    // в момент переключения) — push их дошлёт, фронт с облака не уводим.
+    return 'cloud';
+};
+
+const updateMode = () => {
+    const next = computeMode();
+    if (next !== state.mode) {
+        log(`mode ${state.mode} → ${next}${state.pending ? ` (pending ${state.pending})` : ''}`);
+        if (next === 'draining') {
+            // Перед возвратом в онлайн — последний шанс записям, которые облако отвергало.
+            state.poison.clear();
+        }
+        state.mode = next;
+    }
+    return state.mode;
+};
+
+// ---------------------------------------------------------------- шаги цикла
+
+const snapshotDue = () => {
+    const now = Date.now();
+    if (state.needSnapshot) {
+        if (now < state.snapshotNotBefore) {
+            return false;
+        }
+        return now - state.lastSnapshotTry >= (state.lastSnapshotTry ? SNAPSHOT_RETRY_MS : 0);
+    }
+    return now - state.lastSnapshotOk >= config.intervals().snapshot;
+};
+
+const runSnapshot = async () => {
+    state.lastSnapshotTry = Date.now();
+    const pullFn = isFollower() ? snapshot.pullInitOnly : snapshot.pullSnapshot;
+    const result = await pullFn({store: state.store, cloud: state.cloud});
+    state.needSnapshot = false;
+    state.lastSnapshotOk = Date.now();
+    log(`snapshot applied: ${Object.entries(result.applied).map(([t, n]) => `${t}=${n}`).join(' ')}`);
+
+    if (!isFollower()) {
+        const removed = await state.store.block((s) => mirror.cleanup(s));
+        if (removed) {
+            log(`cleanup: removed ${removed} old closed orders`);
+        }
+    }
+};
+
+const trackFailure = (key, version, reason) => {
+    const entry = state.poison.get(key);
+    if (entry && entry.version === version) {
+        entry.attempts += 1;
+        entry.reason = reason;
+        if (entry.attempts === config.limits().poisonAttempts) {
+            console.error(`[sync] ${key} rejected ${entry.attempts} times, skipped until it changes: ${reason}`);
+        }
+    } else {
+        state.poison.set(key, {version, attempts: 1, reason});
+    }
+};
+
+/** Отравленная запись, которую касса с тех пор правила (или которой больше нет), — снова в работе. */
+const reconcilePoison = () => {
+    for (const [key, entry] of state.poison) {
+        const separator = key.indexOf(':');
+        const row = state.store.get(
+            'SELECT version FROM sync_dirty WHERE entity = ? AND id = ?',
+            [key.slice(0, separator), key.slice(separator + 1)]
+        );
+        if (!row || Number(row.version) !== Number(entry.version)) {
+            state.poison.delete(key);
+        }
+    }
+};
+
+const emitPatches = async (orderIds) => {
+    if (!orderIds.length || state.mode === 'cloud') {
+        return;
+    }
+    // Фронт в cloud-режиме слушает облако; локальный сокет нужен только offline/recovering.
+    const {makeServices} = require('../core');
+    const services = await makeServices({
+        headers: {'team-id': state.session.team_id, 'company-id': state.session.company_id},
+    });
+    for (const id of orderIds) {
+        try {
+            await services.orders.emitPatch(id);
+        } catch (e) {
+            console.error(`[sync] patch emit failed for ${id}:`, e.message);
+        }
+    }
+};
+
+const runPull = async (ids = null, {full = false} = {}) => {
+    let result = {applied: [], skipped: 0, pages: 0, hasMore: false};
+    if (ids) {
+        // Облако отдаёт по ids не больше 200 чеков за раз.
+        for (let i = 0; i < ids.length; i += PULL_IDS_CHUNK) {
+            const part = await mirror.pull({
+                store: state.store, cloud: state.cloud, ids: ids.slice(i, i + PULL_IDS_CHUNK), companyId: sessionCompanyId(),
+            });
+            result = {...part, applied: [...result.applied, ...part.applied], skipped: result.skipped + part.skipped};
+        }
+    } else {
+        result = await mirror.pull({store: state.store, cloud: state.cloud, full, companyId: sessionCompanyId()});
+        state.lastPullAt = Date.now();
+    }
+    await emitPatches(result.applied);
+    return result;
+};
+
+/** Чеки, которые облако попросило перечитать (sync:pull), — одним заходом. */
+const runRequestedPull = async () => {
+    const ids = [...state.pullIds];
+    state.pullIds.clear();
+    try {
+        await runPull(ids);
+    } catch (e) {
+        // Не дошло — вернём в очередь, следующий цикл повторит.
+        for (const id of ids) {
+            state.pullIds.add(id);
+        }
+        throw e;
+    }
+};
+
+/** Эпоха для авторитетной выгрузки: только мастер в local/to_online. */
+const authoritativeEpoch = () => (
+    isMasterNow() && (state.company.state === 'local' || state.company.state === 'to_online')
+        ? state.company.epoch
+        : null
+);
+
+const runPush = async () => {
+    let rounds = 0;
+    reconcilePoison();
+    while (refreshPending() > 0 && rounds < MAX_PUSH_ROUNDS && state.online) {
+        rounds += 1;
+        const epoch = authoritativeEpoch();
+        let result;
+        try {
+            result = await pushBatch({
+                store: state.store,
+                cloud: state.cloud,
+                excluded: excludedKeys(),
+                onFailure: trackFailure,
+                batchSize: state.batchSize,
+                epoch,
+                companyId: sessionCompanyId(),
+            });
+        } catch (e) {
+            state.lastPushError = e.message;
+            if (e.name === 'CloudRequestError') {
+                // Пачку отвергли целиком — дальше по одной, чтобы найти виновную запись.
+                state.batchSize = 1;
+            }
+            throw e;
+        }
+
+        state.lastPushAt = nowIso();
+        if (epoch !== null && result.sent > 0 && !result.authoritative) {
+            // Облако не признало нас мастером этой эпохи — режим сменился, перечитываем его.
+            requestModePoll();
+        }
+        if (result.sent === 0) {
+            break;
+        }
+        if (result.failed.length) {
+            state.lastPushError = result.failed.map((item) => `${item.key}: ${item.reason}`).join('; ');
+        } else {
+            state.lastPushError = null;
+        }
+
+        if (result.conflicts.length) {
+            state.conflicts = [
+                ...result.conflicts.map((item) => ({...item, at: nowIso()})),
+                ...state.conflicts,
+            ].slice(0, MAX_CONFLICTS_KEPT);
+            log(`push conflicts: ${result.conflicts.map((item) => item.id).join(', ')}`);
+            // Облако оставило свою версию — забираем её, локальная копия не должна расходиться.
+            await runPull(result.conflicts.map((item) => item.id));
+        }
+
+        // Облако оставило свою версию принтера (удалён в облаке) — справочник перечитывается снапшотом.
+        if (result.results.some((item) => item.entity === 'printer' && item.status === 'conflict')) {
+            requestSnapshot();
+        }
+
+        const applied = result.results
+            .filter((item) => item.entity === 'order' && item.status === 'applied')
+            .map((item) => item.id);
+        if (applied.length) {
+            log(`pushed ${applied.length} order(s)`);
+        }
+
+        if (result.failed.length) {
+            // Непринятые останутся в очереди; следующая попытка — в следующем цикле.
+            break;
+        }
+    }
+    if (refreshPending() === 0) {
+        state.batchSize = null;
+    }
+};
+
+const pullDue = () => {
+    if (state.mode === 'local' || state.mode === 'draining') {
+        // Истина у этой кассы: облачная копия — её же выгрузка. Расхождения облако присылает
+        // адресно (sync:pull), общий pull по курсору только затирал бы локальные версии.
+        return false;
+    }
+    if (state.pullRequested || state.mode === 'recovering') {
+        return true;
+    }
+    const {pull, pullWithoutSignal} = config.intervals();
+    const every = state.signal && state.signal.connected ? pull : pullWithoutSignal;
+    return Date.now() - state.lastPullAt >= every;
+};
+
+// ---------------------------------------------------------------- режим заведения (модель M)
+
+const requestModePoll = () => {
+    state.modeRequested = true;
+};
+
+const modePollDue = () => state.modeRequested || Date.now() - state.lastModePoll >= config.intervals().modePoll;
+
+const countOpenOrders = () => {
+    try {
+        // Heartbeat уходит в облако заведения сессии — чеки других заведений кассы не в счёт.
+        const companyId = sessionCompanyId();
+        return Number(state.store.get(
+            `SELECT COUNT(*) AS count FROM orders WHERE closed_at IS NULL AND deleted_at IS NULL${companyId ? ' AND company_id = ?' : ''}`,
+            companyId ? [String(companyId)] : []
+        ).count) || 0;
+    } catch (e) {
+        return null;
+    }
+};
+
+const dbFile = () => (state.store && state.store.database ? state.store.database.file : null);
+
+/** Итог сверки для суперадминки и /local/status. null — сверок ещё не было. */
+const reconcileStatus = () => {
+    const r = state.reconcile;
+    if (!r.at) {
+        return null;
+    }
+    return {
+        at: r.at,
+        ok: r.ok,
+        streak: r.streak,
+        alarm: r.streak >= config.reconcile().alarmAfter,
+        local: r.local,
+        cloud: r.cloud,
+        diff: r.diff,
+        truncated: r.truncated,
+        healed: r.healed,
+        error: r.error,
+    };
+};
+
+/** Heartbeat кассы для суперадминки (PosModeService::heartbeat берёт только эти поля). */
+const heartbeat = () => ({
+    mode: state.mode,
+    role: config.role(),
+    version: PACKAGE_VERSION,
+    pending: state.pending,
+    poisoned: excludedKeys().size,
+    last_push_at: state.lastPushAt,
+    last_push_error: state.lastPushError,
+    last_pull_at: state.lastPullAt ? new Date(state.lastPullAt).toISOString() : null,
+    snapshot_at: state.store ? kv.get(state.store, 'snapshot_at') : null,
+    cloud_reachable: state.online,
+    totals: {open: countOpenOrders()},
+    epoch: state.company ? state.company.epoch : null,
+    monitor: monitor.snapshot({dbFile: dbFile()}),
+    reconcile: reconcileStatus(),
+    // Адрес мастера для LAN-перехода браузера (LanHandoffService::masterFor).
+    ...(config.isLanFrontEnabled() ? {lan: lanFront.heartbeat(getConfig().port)} : {}),
+});
+
+const sameCompanyMode = (a, b) => Boolean(a && b)
+    && a.company_id === b.company_id
+    && a.state === b.state
+    && a.master_terminal_id === b.master_terminal_id
+    && a.epoch === b.epoch
+    && a.enabled === b.enabled;
+
+/**
+ * Режим заведения из ответа облака (sync.mode целиком или state из claim/release).
+ * Хранится в kv: мастер, перезапущенный без интернета, обязан помнить, что он мастер.
+ */
+const applyCompanyMode = async (data) => {
+    if (!data || typeof data !== 'object' || !state.session) {
+        return;
+    }
+    const previous = state.company && state.company.company_id === state.session.company_id ? state.company : null;
+    const next = {
+        company_id: state.session.company_id,
+        state: COMPANY_STATES.has(data.state) ? data.state : 'online',
+        master_terminal_id: data.master_terminal_id ? String(data.master_terminal_id) : null,
+        epoch: Number(data.epoch) || 0,
+        // claim/release отвечают без enabled — переходы возможны только при включённом режиме
+        enabled: data.enabled !== undefined ? Boolean(data.enabled) : Boolean(previous && previous.enabled),
+    };
+    if (sameCompanyMode(previous, next)) {
+        return;
+    }
+    const role = next.master_terminal_id === state.session.terminal_id ? 'master' : 'not master';
+    log(`company mode ${previous ? previous.state : '?'} → ${next.state} (epoch ${next.epoch}, ${role}${next.enabled ? '' : ', disabled'})`);
+    state.company = {...next, at: nowIso()};
+    await state.store.block((s) => kv.set(s, 'company_mode', state.company));
+};
+
+const pollMode = async () => {
+    state.lastModePoll = Date.now();
+    state.modeRequested = false;
+    let response;
+    try {
+        response = await state.cloud.call('sync.mode', {status: heartbeat()});
+    } catch (e) {
+        state.lastModeError = e.message;
+        if (e.name === 'CloudRequestError' && e.status === 404) {
+            // Старый Laravel или Sync API выключен: модели M нет — заведение в онлайне.
+            await applyCompanyMode({state: 'online', master_terminal_id: null, epoch: 0, enabled: false});
+            return;
+        }
+        throw e;
+    }
+    state.lastModeError = null;
+    await applyCompanyMode(response);
+};
+
+/** Ответ claim/release (успех или 409 с state) — режим, который облако считает верным. */
+const applyHandoverResponse = async (body) => {
+    if (body && body.state && typeof body.state === 'object') {
+        await applyCompanyMode(body.state);
+    }
+};
+
+const handoverDue = () => isMasterNow()
+    && state.company.state === 'to_local'
+    && Date.now() - state.handover.lastTry >= HANDOVER_RETRY_MS;
+
+/**
+ * to_local → local. Облако уже не принимает правок (409 mode_switching), поэтому копия,
+ * которую касса забирает, полная. Любой сбой — повтор через HANDOVER_RETRY_MS с начала:
+ * каждый шаг идемпотентен.
+ */
+const runHandover = async () => {
+    const epoch = state.company.epoch;
+    const stage = (name) => {
+        state.handover = {...state.handover, stage: name, epoch, at: nowIso()};
+    };
+    state.handover.lastTry = Date.now();
+    state.handover.error = null;
+    try {
+        // 1. Своё недосланное — наверх: забранная копия должна его уже содержать.
+        stage('push');
+        await runPush();
+        if (refreshPending() > 0) {
+            throw new Error(`${state.pending} unsent record(s)`);
+        }
+
+        // 2. Облачная копия чеков: открытые + последние 36 ч, дальше по курсору до конца.
+        stage('pull');
+        let result = await runPull(null, {full: true});
+        let rounds = 0;
+        while (result.hasMore && rounds < MAX_HANDOVER_PULL_ROUNDS) {
+            rounds += 1;
+            result = await runPull();
+        }
+        if (result.hasMore) {
+            throw new Error('orders pull did not finish');
+        }
+
+        // 3. Чеки, открытые локально, но не попавшие в выборку (закрыты/удалены в облаке давно):
+        //    облачная версия важнее — перечитываем по ids.
+        const openIds = state.store
+            .all('SELECT id FROM orders WHERE closed_at IS NULL AND deleted_at IS NULL')
+            .map((row) => row.id);
+        if (openIds.length) {
+            await runPull(openIds);
+        }
+
+        // 4. Справочники — свежие: мастер будет работать без облака.
+        stage('snapshot');
+        await runSnapshot();
+
+        // 5. Режим мог смениться, пока шла загрузка (отмена, другой мастер).
+        await pollMode();
+        if (!isMasterNow() || state.company.state !== 'to_local' || state.company.epoch !== epoch) {
+            stage(null);
+            return;
+        }
+        if (refreshPending() > 0) {
+            throw new Error(`${state.pending} record(s) changed during handover`);
+        }
+
+        stage('claim');
+        let response;
+        try {
+            response = await state.cloud.call('sync.claimMaster', {epoch});
+        } catch (e) {
+            if (e.name === 'CloudRequestError') {
+                await applyHandoverResponse(e.body);
+                requestModePoll();
+            }
+            throw e;
+        }
+        await applyHandoverResponse(response);
+        stage(null);
+        log(`claimed company as master (epoch ${epoch})`);
+    } catch (e) {
+        state.handover.error = e.message;
+        throw e;
+    }
+};
+
+/** to_online → online: очередь пуста — отдаём заведение облаку. */
+const runRelease = async () => {
+    if (!isMasterNow() || state.company.state !== 'to_online' || refreshPending() > 0) {
+        return;
+    }
+    const epoch = state.company.epoch;
+    let response;
+    try {
+        response = await state.cloud.call('sync.releaseMaster', {epoch});
+    } catch (e) {
+        if (e.name === 'CloudRequestError') {
+            await applyHandoverResponse(e.body);
+            requestModePoll();
+        }
+        throw e;
+    }
+    await applyHandoverResponse(response);
+    log(`released company to cloud (epoch ${epoch})`);
+};
+
+// ---------------------------------------------------------------- ретрансляция (модель M)
+
+/** Касса обслуживает заведение как мастер и принимает события клиентов облака. */
+const isServingAsMaster = () => !isFollower() && isMasterNow()
+    && (state.mode === 'local' || state.mode === 'draining');
+
+const headerValue = (headers, name) => {
+    const key = Object.keys(headers).find((item) => item.toLowerCase() === name);
+    return key ? headers[key] : null;
+};
+
+/**
+ * master:request — событие клиента облака, ретранслированное Laravel → облачный Node → сюда.
+ * Ответ {relayed:true, status, body} уходит клиенту как есть; relayed:false — «мастера нет».
+ */
+const handleMasterRequest = async (payload) => {
+    const session = state.session;
+    const epoch = Number(payload.epoch);
+    if (!session || !isServingAsMaster()
+        || payload.company_id !== session.company_id
+        || payload.master_terminal_id !== session.terminal_id
+        || epoch !== state.company.epoch) {
+        // Облако считает мастером нас, а мы — нет (или эпоха другая): сверяемся с ним.
+        requestModePoll();
+        wake();
+        return {relayed: false, error_code: 'not_master'};
+    }
+
+    const event = String(payload.event || '');
+    const headers = payload.headers && typeof payload.headers === 'object' ? {...payload.headers} : {};
+    const params = payload.params && typeof payload.params === 'object' ? payload.params : {};
+    const core = require('../core');
+    if (RELAY_DENY.test(event) || !core.canHandle(event)) {
+        return {
+            relayed: true,
+            status: 409,
+            body: {success: false, error_code: 'not_supported_in_local_mode', message: 'Bu əməliyyat lokal rejimdə mümkün deyil'},
+        };
+    }
+
+    // Заведение — только своё: заголовок компании облако проверило токеном, но ядро кассы
+    // не должно даже пытаться работать с чужой.
+    const companyHeader = headerValue(headers, 'company-id');
+    if (companyHeader && companyHeader !== session.company_id) {
+        return {relayed: true, status: 403, body: {success: false, message: 'Company mismatch'}};
+    }
+    headers['company-id'] = session.company_id;
+    headers['team-id'] = session.team_id;
+
+    try {
+        const body = await core.dispatch(event, {headers, params});
+        return {relayed: true, status: 200, body};
+    } catch (e) {
+        if (e instanceof HttpError) {
+            return {relayed: true, status: e.status, body: e.body};
+        }
+        console.error(`[sync] relayed ${event} failed:`, e);
+        return {relayed: true, status: 500, body: {success: false, message: e.message}};
+    }
+};
+
+/** Облако просит перечитать чеки (правка мимо мастера принята по правилам модели F). */
+const requestPull = (ids) => {
+    for (const id of ids) {
+        if (id) {
+            state.pullIds.add(String(id));
+        }
+    }
+    kick();
+};
+
+/** Бродкаст облака (KDS, клиентские события терминалов облака) → локальные клиенты мастера. */
+const forwardCloudBroadcast = (eventName, args) => {
+    if (!isServingAsMaster() || !require('../socket/server')()) {
+        return;
+    }
+    try {
+        require('../socket/server')().to(String(state.session.company_id)).emit(eventName, ...args);
+    } catch (e) {
+        console.error('[sync] cloud broadcast forward failed:', e.message);
+    }
+};
+
+/**
+ * Бродкаст ядра/клиентов мастера → клиенты заведения, подключённые к облаку.
+ * No-op, пока касса не мастер: в остальных режимах облако рассылает само.
+ */
+const relayBroadcast = (eventName, args) => {
+    if (!isServingAsMaster() || !state.signal) {
+        return false;
+    }
+    return state.signal.broadcast(eventName, args);
+};
+
+/**
+ * Запрос к терминалу, которого нет в локальном сокете (печать на терминал облака).
+ * null — не применимо (касса не мастер или канала нет).
+ */
+const terminalRequest = (options) => {
+    if (!isServingAsMaster() || !state.signal) {
+        return null;
+    }
+    return state.signal.terminalRequest(options);
+};
+
+// ---------------------------------------------------------------- сверка с облаком
+
+const reconcileDue = () => config.isReconcileEnabled()
+    && !isFollower()
+    && Boolean(state.session)
+    && hasInit()
+    // local — касса мастер, облако получает её копию; cloud — обычный режим. Переходы,
+    // офлайн и досылка пропускаются: расхождение там ожидаемо.
+    && (state.mode === 'cloud' || state.mode === 'local')
+    && !(isMasterNow() && state.company.state === 'to_local')
+    && state.pullIds.size === 0
+    && refreshPending() === 0
+    && Date.now() >= state.reconcile.nextAt;
+
+const runReconcile = async () => {
+    const settings = config.reconcile();
+    const previous = state.reconcile;
+    previous.nextAt = Date.now() + settings.interval;
+    let result;
+    try {
+        result = await reconcile.run({
+            store: state.store,
+            cloud: state.cloud,
+            companyId: state.session.company_id,
+            authoritative: authoritativeEpoch() !== null,
+            skip: excludedKeys(),
+        });
+    } catch (e) {
+        previous.at = nowIso();
+        if (e.name === 'CloudRequestError' && e.status === 404) {
+            // Laravel без sync.reconcile (или Sync API выключен) — спросим снова через час.
+            previous.error = 'unsupported';
+            previous.nextAt = Date.now() + 3600000;
+            return;
+        }
+        previous.error = e.message;
+        throw e;
+    }
+
+    const size = reconcile.diffSize(result.diff);
+    // Сводки разошлись, а построчно всё сходится (копейки округления) — это не расхождение.
+    const mismatched = !result.ok && (result.truncated || size > 0);
+    const healed = result.push.length + result.pull.length;
+    const counts = result.diff ? Object.fromEntries(
+        Object.entries(result.diff).map(([kind, ids]) => [kind, ids.length])
+    ) : null;
+    state.reconcile = {
+        ...previous,
+        at: nowIso(),
+        ok: !mismatched,
+        streak: mismatched ? previous.streak + 1 : 0,
+        local: result.local,
+        cloud: result.cloud,
+        diff: mismatched ? counts : null,
+        truncated: result.truncated,
+        healed: previous.healed + healed,
+        error: null,
+        nextAt: mismatched ? Date.now() + settings.retry : previous.nextAt,
+    };
+    if (!mismatched) {
+        return;
+    }
+
+    const message = `reconcile mismatch #${state.reconcile.streak}: local ${result.local.count}/${result.local.total}`
+        + ` cloud ${result.cloud ? `${result.cloud.count}/${result.cloud.total}` : '?'}`
+        + (counts ? ` ${JSON.stringify(counts)}` : ' (cloud list truncated)')
+        + `; push ${result.push.length}, pull ${result.pull.length}`;
+    if (state.reconcile.streak >= settings.alarmAfter) {
+        console.error(`[sync] ${message}`);
+    } else {
+        log(message);
+    }
+    for (const id of result.pull) {
+        state.pullIds.add(id);
+    }
+    if (result.push.length) {
+        refreshPending();
+    }
+    if (healed) {
+        kick();
+    }
+};
+
+const checkMaster = async () => {
+    const url = config.masterUrl();
+    if (!url) {
+        state.master = {reachable: false, mode: null, checkedAt: nowIso(), error: 'master not found'};
+        return;
+    }
+    try {
+        const response = await axios.get(`${url}/local/status`, {
+            headers: lanHeaders(),
+            timeout: config.timeouts().health,
+            validateStatus: () => true,
+        });
+        const body = response.data;
+        if (response.status !== 200 || !body || typeof body.mode !== 'string') {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        state.master = {reachable: true, mode: body.enabled ? body.mode : 'cloud', checkedAt: nowIso(), error: null};
+    } catch (e) {
+        state.master = {reachable: false, mode: null, checkedAt: nowIso(), error: e.message};
+        // Мастер мог сменить адрес (DHCP) — искать сразу, не дожидаясь интервала поиска.
+        if (state.finder) {
+            state.finder.kick();
+        }
+    }
+};
+
+const step = async (name, fn) => {
+    try {
+        await fn();
+    } catch (e) {
+        // CloudUnavailable уже учтён в гистерезисе через onLink; 4xx и прочее — просто в статус.
+        if (e.name !== 'CloudUnavailable') {
+            console.error(`[sync] ${name} failed:`, e.message);
+        }
+        if (name === 'snapshot') {
+            state.lastError = `${name}: ${e.message}`;
+        }
+    }
+};
+
+const cycle = async () => {
+    if (!state.session || !state.cloud) {
+        updateMode();
+        return;
+    }
+    await state.cloud.health();
+
+    if (isFollower()) {
+        await checkMaster();
+        if (state.online && snapshotDue()) {
+            await step('snapshot', runSnapshot);
+        }
+        await runLogout();
+        updateMode();
+        return;
+    }
+
+    if (state.online && modePollDue()) {
+        await step('mode', pollMode);
+    }
+    updateMode();
+    if (state.online) {
+        if (snapshotDue()) {
+            await step('snapshot', runSnapshot);
+        }
+        if (config.isLanFrontEnabled()) {
+            // Реестр телефонов нужен до обрыва: без облака взять его неоткуда.
+            if (lanDevices.due()) {
+                await step('lan devices', () => lanDevices.refresh(state.cloud, state.store));
+            }
+            // Загрузка фронта может длиться минуты — цикл её не ждёт.
+            if (lanFront.due()) {
+                lanFront.kick();
+            }
+        }
+        if (hasInit()) {
+            if (handoverDue()) {
+                await step('handover', runHandover);
+                updateMode();
+            }
+            await step('push', runPush);
+            updateMode();
+            if (state.mode === 'draining') {
+                await step('release', runRelease);
+                updateMode();
+            }
+            if (state.online && state.pullIds.size) {
+                await step('pull ids', runRequestedPull);
+            }
+            if (state.online && pullDue()) {
+                state.pullRequested = false;
+                await step('pull', () => runPull());
+            }
+            if (state.online && reconcileDue()) {
+                await step('reconcile', runReconcile);
+            }
+        }
+    }
+    await runLogout();
+    updateMode();
+};
+
+// ---------------------------------------------------------------- цикл
+
+const schedule = (delay = config.intervals().tick) => {
+    clearTimeout(state.timer);
+    if (!state.started) {
+        return;
+    }
+    state.timer = setTimeout(runLoop, delay);
+    if (state.timer.unref) {
+        state.timer.unref();
+    }
+};
+
+const runLoop = async () => {
+    if (state.running) {
+        state.rerun = true;
+        return;
+    }
+    state.running = true;
+    try {
+        await cycle();
+    } catch (e) {
+        console.error('[sync] cycle failed:', e);
+    } finally {
+        state.running = false;
+    }
+    if (state.rerun) {
+        state.rerun = false;
+        schedule(0);
+    } else {
+        schedule();
+    }
+};
+
+/** Облако поменяло справочник, который касса правит и сама (sync:snapshot). */
+const requestSnapshot = () => {
+    state.needSnapshot = true;
+    state.lastSnapshotTry = 0;
+    state.snapshotNotBefore = state.lastSnapshotOk + SNAPSHOT_SIGNAL_MIN_MS;
+    kick();
+};
+
+/** Внеочередной цикл (сигнал облака «что-то поменялось»), с дебаунсом. */
+const wake = () => {
+    state.pullRequested = true;
+    kick();
+};
+
+/** Внеочередной цикл без pull по курсору (режим заведения, pull по ids). */
+const kick = () => {
+    clearTimeout(state.wakeTimer);
+    state.wakeTimer = setTimeout(() => {
+        if (state.running) {
+            state.rerun = true;
+        } else {
+            schedule(0);
+        }
+    }, config.intervals().signalDebounce);
+    if (state.wakeTimer.unref) {
+        state.wakeTimer.unref();
+    }
+};
+
+// ---------------------------------------------------------------- сессия
+
+const SESSION_FIELDS = ['token', 'team_id', 'company_id', 'terminal_id', 'employee_id', 'api_url'];
+const IDENTITY_FIELDS = ['token', 'team_id', 'company_id', 'terminal_id', 'api_url'];
+
+const sanitizeSession = (input = {}) => {
+    const session = {};
+    for (const field of SESSION_FIELDS) {
+        const value = input[field];
+        session[field] = value === undefined || value === null || value === '' ? null : String(value);
+    }
+    if (session.api_url) {
+        session.api_url = normalizeApiUrl(session.api_url);
+    }
+    return session;
+};
+
+const stopComponents = () => {
+    if (state.signal) {
+        state.signal.stop();
+        state.signal = null;
+    }
+    if (state.bridge) {
+        state.bridge.stop();
+        state.bridge = null;
+    }
+    state.cloud = null;
+};
+
+/** Мост ведомого к мастеру: при auto — только когда мастер найден, заново — при смене адреса. */
+const startBridge = () => {
+    if (state.bridge) {
+        state.bridge.stop();
+        state.bridge = null;
+    }
+    const masterUrl = config.masterUrl();
+    if (!state.session || !masterUrl) {
+        return;
+    }
+    state.bridge = new MasterBridge({
+        masterUrl,
+        session: state.session,
+        isRelaying: () => state.mode !== 'cloud',
+    }).start();
+};
+
+const onMasterFound = () => {
+    state.master = {reachable: null, mode: null, checkedAt: null, error: null};
+    if (isFollower()) {
+        startBridge();
+    }
+    kick();
+};
+
+const startDiscovery = () => {
+    stopDiscovery();
+    if (isFollower() && config.isMasterAuto()) {
+        state.finder = new discovery.Finder({
+            companyId: () => (state.session ? state.session.company_id : null),
+            isReachable: () => state.master.reachable,
+            onChange: onMasterFound,
+            // адрес мастера переживает перезапуск ведомого: первым проверяется он
+            remembered: () => (state.store ? kv.get(state.store, 'discovery_master') : null),
+            remember: (url) => {
+                if (state.store) {
+                    state.store.block((s) => kv.set(s, 'discovery_master', url))
+                        .catch((e) => console.warn('[discovery] remember failed:', e.message));
+                }
+            },
+        }).start();
+    } else if (config.role() === 'master' && config.lanKey()) {
+        state.responder = new discovery.Responder({
+            httpPort: () => getConfig().port,
+            identity: () => state.session,
+        }).start();
+    }
+};
+
+/** Ответ мастера на GET /local/whoami (ступени поиска ведомого). null — 404. */
+const whoami = (nonce) => (config.role() === 'master' && state.started
+    ? discovery.whoami({nonce, httpPort: getConfig().port, identity: state.session})
+    : null);
+
+/**
+ * Ответ мастера на GET /local/lan — опрос телефона, ушедшего на мастера по LAN: пора ли назад в
+ * облако. Назад можно, когда облако доступно самому мастеру и заведение не держит истину на кассе
+ * в переходе (draining/recovering досылают очередь). null — 404.
+ */
+const lanInfo = () => {
+    if (!config.isLanFrontEnabled() || !state.started) {
+        return null;
+    }
+    return {
+        lan: true,
+        mode: mode(),
+        cloud_reachable: state.online === true,
+        front_version: lanFront.status().version,
+    };
+};
+
+const stopDiscovery = () => {
+    if (state.finder) {
+        state.finder.stop();
+        state.finder = null;
+    }
+    if (state.responder) {
+        state.responder.stop();
+        state.responder = null;
+    }
+};
+
+const startComponents = () => {
+    stopComponents();
+    const session = state.session;
+    if (!session) {
+        return;
+    }
+    state.cloud = new CloudClient(session, {onLink});
+    if (isFollower()) {
+        startBridge();
+    } else {
+        state.signal = new CloudSignal({
+            session,
+            onChange: wake,
+            onSnapshot: requestSnapshot,
+            master: {
+                isLocal: isServingAsMaster,
+                onRequest: handleMasterRequest,
+                onPull: requestPull,
+                onMode: () => {
+                    requestModePoll();
+                    kick();
+                },
+                onBroadcast: forwardCloudBroadcast,
+            },
+        }).start();
+    }
+};
+
+/**
+ * Сессия терминала от фронта (POST /local/session): токен и заголовки, с которыми синк ходит
+ * в облако. Смена личности (токен/компания/терминал/адрес) перезапускает клиентов и снапшот;
+ * смена сотрудника — просто обновляет заголовок.
+ */
+const setSession = async (input) => {
+    if (!config.isSyncEnabled()) {
+        return {success: false, enabled: false};
+    }
+    await start();
+    const next = sanitizeSession(input);
+    if (!next.token || !next.company_id || !next.team_id || !next.api_url) {
+        return {success: false, message: 'token, team_id, company_id and api_url are required'};
+    }
+
+    const previous = state.session;
+    const identityChanged = !previous || IDENTITY_FIELDS.some((field) => previous[field] !== next[field]);
+    // Терминал вышел, пока токен ещё не отозван, а вошли уже с другим — старый отзовёт очередь.
+    const orphan = previous && previous.parked && previous.token !== next.token ? previous : null;
+
+    await state.store.block((s) => {
+        kv.set(s, 'session', next);
+        if (orphan) {
+            queueLogout(s, orphan);
+        }
+        // С этого момента каждый чек заведения проходит через эту кассу (сама создала или
+        // получит pull'ом). Первый pull сдвинет начало назад на окно облака.
+        mirror.extendHistory(s, next.company_id, new Date());
+    });
+
+    if (identityChanged) {
+        if (previous && previous.company_id !== next.company_id && refreshPending() > 0) {
+            // Не потеряются: уйдут, когда касса снова войдёт в то заведение (push берёт записи
+            // только заведения сессии, снапшот и уборка помеченное не трогают).
+            console.warn(`[sync] company changed: ${state.pending} unsent record(s) of the previous company wait for its next login`);
+        }
+        if (previous && previous.company_id !== next.company_id) {
+            // Токены чужого заведения больше не годятся.
+            await lanDevices.reset(state.store);
+        }
+        state.session = next;
+        state.needSnapshot = true;
+        state.lastSnapshotTry = 0;
+        state.snapshotNotBefore = 0;
+        state.handover.lastTry = 0;
+        state.pullIds.clear();
+        // Другая касса/компания — прошлые итоги сверки к ней не относятся; первая сверка —
+        // после того, как зеркало догонит облако.
+        state.reconcile = {...state.reconcile, nextAt: Date.now() + config.reconcile().retry,
+            at: null, ok: null, streak: 0, local: null, cloud: null, diff: null, truncated: false, error: null};
+        requestModePoll();
+        startComponents();
+        schedule(0);
+    } else if (state.session) {
+        // Тот же объект держат облачный клиент и сокеты — меняем поля на месте.
+        Object.assign(state.session, next);
+        // Фронт снова прислал сессию — значит, терминал вошёл обратно (resume).
+        delete state.session.parked;
+    }
+    state.revokeWaitFrom = null;
+    return {success: true, mode: state.mode};
+};
+
+/** Выход терминала: токен забываем. Недосланные правки остаются и уйдут со следующей сессией. */
+const clearSession = async () => {
+    if (!config.isSyncEnabled()) {
+        return {success: false, enabled: false};
+    }
+    await start();
+    if (isServingAsMaster()) {
+        // Без сессии касса перестаёт обслуживать заведение: клиенты облака получат 503.
+        console.warn('[sync] session cleared on the master terminal — company is not served until the next login');
+    }
+    stopComponents();
+    state.session = null;
+    state.revokeWaitFrom = null;
+    await state.store.block((s) => kv.del(s, 'session'));
+    updateMode();
+    return {success: true};
+};
+
+// ---------------------------------------------------------------- выход терминала
+
+/*
+ * Выход терминала (logout) без облака. Раньше фронт сам отзывал токен в облаке
+ * (auth.logoutApp) и стирал сессию синка: без интернета выход падал, а недосланное
+ * ждало следующего входа, которого без интернета не бывает (app.auth — только облако).
+ *
+ * Теперь выход «паркует» сессию: фронт свою авторизацию стирает, а синк токен держит, пока
+ * он нужен, — досылает очередь, а мастер модели M продолжает обслуживать зал. Токен
+ * отзывается, когда облако на связи, очередь пуста и касса не держит заведение
+ * (очередь не опустела за OFFLINE_LOGOUT_GRACE_MS — отзыв всё равно, недосланное уйдёт со
+ * следующим входом в это заведение). До отзыва на кассу можно вернуться по PIN сотрудника
+ * (resume) — это единственный вход без облака.
+ */
+
+const initNames = () => {
+    const blob = state.store ? kv.get(state.store, 'init') : null;
+    const name = (value) => (value && value.name ? String(value.name) : null);
+    return {
+        terminal: name(blob && blob.terminal),
+        company: blob && blob.terminal && blob.terminal.company_name ? String(blob.terminal.company_name) : null,
+        team: name(blob && blob.team),
+    };
+};
+
+/** Токен прошлой сессии — в очередь на отзыв (внутри store.block). */
+const queueLogout = (s, session) => {
+    const queue = (kv.get(s, 'logout_queue') || []).filter((entry) => entry.token !== session.token);
+    queue.push({
+        token: session.token,
+        team_id: session.team_id,
+        company_id: session.company_id,
+        terminal_id: session.terminal_id,
+        api_url: session.api_url,
+        at: nowIso(),
+    });
+    kv.set(s, 'logout_queue', queue.slice(-MAX_LOGOUT_QUEUE));
+};
+
+/**
+ * Отзыв токена в облаке. true — токена больше нет (отозван сейчас или уже был мёртв: любой 4xx),
+ * false — облако недоступно, повторить позже.
+ */
+const revokeToken = async (client, data = {}, timeout = config.timeouts().api) => {
+    try {
+        await client.call('auth.logoutApp', data, {timeout});
+        return true;
+    } catch (e) {
+        if (e instanceof CloudRequestError) {
+            return true;
+        }
+        if (e.name !== 'CloudUnavailable') {
+            console.error('[sync] logout failed:', e.message);
+        }
+        return false;
+    }
+};
+
+const canRevokeParked = () => Boolean(state.session && state.session.parked && state.cloud)
+    && state.online === true && !state.revoking && !isServingAsMaster();
+
+/** Отзыв токена запаркованной сессии. Вернулись на кассу, пока шёл запрос, — сессию не трогаем. */
+const revokeParked = async (timeout) => {
+    const session = state.session;
+    state.revoking = true;
+    let revoked;
+    try {
+        revoked = await revokeToken(state.cloud, {}, timeout);
+    } finally {
+        state.revoking = false;
+    }
+    if (!revoked || state.session !== session) {
+        return false;
+    }
+    log('terminal logged out: token revoked');
+    await clearSession();
+    return true;
+};
+
+const runRevoke = async () => {
+    if (!canRevokeParked()) {
+        state.revokeWaitFrom = null;
+        return;
+    }
+    if (refreshPending() > 0) {
+        state.revokeWaitFrom = state.revokeWaitFrom || Date.now();
+        if (Date.now() - state.revokeWaitFrom < config.intervals().logoutGrace) {
+            return;
+        }
+        console.warn(`[sync] logout: ${state.pending} unsent record(s) still queued after the grace period — `
+            + 'revoking the token anyway, they wait for the next login to this company');
+    }
+    await revokeParked();
+};
+
+/** Токены прошлых сессий: у каждого свой клиент — сессия кассы тут уже другая. */
+const runLogoutQueue = async () => {
+    const queue = kv.get(state.store, 'logout_queue') || [];
+    for (const entry of queue) {
+        // Тот же терминал уже вошёл с новым токеном — отметку «вошёл» облаку не сбрасывать.
+        const sameTerminal = Boolean(state.session && entry.terminal_id && entry.terminal_id === state.session.terminal_id);
+        if (!await revokeToken(new CloudClient(entry), sameTerminal ? {keep_terminal: true} : {})) {
+            return;
+        }
+        await state.store.block((s) => kv.set(s, 'logout_queue',
+            (kv.get(s, 'logout_queue') || []).filter((item) => item.token !== entry.token)));
+    }
+};
+
+const runLogout = async () => {
+    if (state.online === true && state.store && (kv.get(state.store, 'logout_queue') || []).length) {
+        await step('logout queue', runLogoutQueue);
+    }
+    await step('revoke', runRevoke);
+};
+
+/**
+ * POST /local/logout от фронта. Сессия не та (фронт вышел с другим токеном) — handled: false,
+ * фронт выходит по-старому. Иначе сессия паркуется и, если можно, токен отзывается сразу.
+ */
+const logout = async ({token} = {}) => {
+    if (!config.isSyncEnabled()) {
+        return {success: false, enabled: false};
+    }
+    await start();
+    const session = state.session;
+    if (!session || !token || session.token !== String(token)) {
+        return {success: true, handled: false};
+    }
+    if (!session.parked) {
+        session.parked = {at: nowIso(), ...initNames()};
+        await state.store.block((s) => kv.set(s, 'session', {...session}));
+    }
+    if (canRevokeParked() && refreshPending() === 0 && await revokeParked(REVOKE_TIMEOUT_MS)) {
+        return {success: true, handled: true, revoked: true};
+    }
+    if (isServingAsMaster()) {
+        console.warn('[sync] terminal logged out on the master — the company is still served, token kept');
+    }
+    schedule(0);
+    return {success: true, handled: true, parked: true, pending: state.pending, master: isServingAsMaster()};
+};
+
+/**
+ * POST /local/resume — вход обратно на запаркованную сессию по PIN сотрудника. PIN проверяется,
+ * как в офлайн-auth.unlock (тот же список users и тот же счётчик неудач). Отдаёт то, что фронт
+ * кладёт в auth-user / auth-team / auth-terminal.
+ */
+const resume = async ({code} = {}) => {
+    if (!config.isSyncEnabled()) {
+        return {success: false, enabled: false};
+    }
+    await start();
+    const session = state.session;
+    if (!session || !session.parked) {
+        throw new HttpError(409, {success: false, error_code: 'not_parked', message: 'Terminal is not logged out'});
+    }
+    const busy = () => new HttpError(409, {
+        success: false,
+        error_code: 'logout_in_progress',
+        message: 'Terminaldan çıxış tamamlanır, yenidən daxil olun',
+    });
+    if (state.revoking) {
+        throw busy();
+    }
+    const blob = kv.get(state.store, 'init');
+    if (!blob || typeof blob !== 'object') {
+        throw new HttpError(503, {success: false, error_code: 'offline_not_ready', message: 'Offline data is not ready yet'});
+    }
+    const key = throttleKey(session.team_id, session.terminal_id);
+    unlockThrottle.assertAllowed(key);
+    const user = code
+        ? await findUnlockUser(state.store, Array.isArray(blob.users) ? blob.users : [], code, blob.pin_salt)
+        : null;
+    if (!user) {
+        unlockThrottle.fail(key);
+        throw new HttpError(422, {success: false, error_code: 'invalid_code', message: 'PIN kod yanlışdır'});
+    }
+    unlockThrottle.reset(key);
+    // Пока проверялся PIN, мог начаться отзыв или прийти другая сессия.
+    if (state.session !== session || !session.parked || state.revoking) {
+        throw busy();
+    }
+    delete session.parked;
+    state.revokeWaitFrom = null;
+    await state.store.block((s) => kv.set(s, 'session', {...session}));
+    log('terminal logged back in by PIN');
+    return {
+        success: true,
+        user: {...(blob.user && typeof blob.user === 'object' ? blob.user : {}), token: session.token},
+        team: blob.team || null,
+        terminal: blob.terminal || null,
+    };
+};
+
+// ---------------------------------------------------------------- старт / статус
+
+const boot = async () => {
+    const store = await getStore();
+    // Строка подавления переживает только крах посреди блока — снимаем её на всякий случай,
+    // иначе триггеры молчали бы и офлайн-правки не попали бы в очередь.
+    await store.block((s) => s.run('DELETE FROM sync_suppress'));
+    state.store = store;
+    state.session = kv.get(store, 'session');
+    // Мастер, перезапущенный без интернета, продолжает работать по сохранённому режиму.
+    state.company = kv.get(store, 'company_mode');
+    state.started = true;
+    state.reconcile.nextAt = Date.now() + config.reconcile().retry;
+    // Копии с диска: мастер, перезапущенный без интернета, должен узнать телефоны и отдать фронт.
+    lanDevices.load(store);
+    lanFront.load();
+    monitor.start();
+    startDiscovery();
+    startComponents();
+    updateMode();
+    log(`started: role=${config.role()} mode=${state.mode}${state.session ? '' : ' (no session yet)'}`);
+    schedule(0);
+};
+
+const start = () => {
+    if (!config.isSyncEnabled()) {
+        return Promise.resolve(false);
+    }
+    if (!state.starting) {
+        state.starting = boot().then(() => true).catch((e) => {
+            console.error('[sync] start failed:', e);
+            state.starting = null;
+            return false;
+        });
+    }
+    return state.starting;
+};
+
+const stop = () => {
+    state.started = false;
+    clearTimeout(state.timer);
+    clearTimeout(state.wakeTimer);
+    stopComponents();
+    stopDiscovery();
+    monitor.stop();
+    state.starting = null;
+};
+
+/** Текущий режим для ядра и фронта. null — синк выключен (поведение как до модели F). */
+const mode = () => (config.isSyncEnabled() ? state.mode : null);
+
+/** Фронту и ведомым: куда ходить и что с синком. */
+const status = () => {
+    const enabled = config.isSyncEnabled();
+    const store = state.store;
+    const read = (key) => (store ? kv.get(store, key) : null);
+    const excluded = [...state.poison.entries()]
+        .filter(([, entry]) => entry.attempts >= config.limits().poisonAttempts)
+        .map(([key, entry]) => ({key, attempts: entry.attempts, reason: entry.reason}));
+
+    const result = {
+        enabled,
+        mode: enabled ? state.mode : 'cloud',
+        role: config.role(),
+        session: Boolean(state.session),
+        // терминал вышел, токен ещё не отозван: на кассу можно вернуться по PIN (resume)
+        parked: state.session && state.session.parked
+            ? {...state.session.parked, revoking: state.revoking}
+            : null,
+        cloud: {
+            reachable: state.online,
+            last_ok_at: state.lastOkAt,
+            last_error: state.lastError,
+        },
+        sync: {
+            snapshot_at: read('snapshot_at'),
+            orders_cursor: read(mirror.cursorKey(sessionCompanyId())),
+            pending_push: state.pending,
+            // Недосланное других заведений этой кассы: [{company_id, count}], уйдёт при входе в них.
+            other_companies: state.foreignPending || [],
+            last_push_at: state.lastPushAt,
+            last_push_error: state.lastPushError,
+            last_pull_at: state.lastPullAt ? new Date(state.lastPullAt).toISOString() : null,
+            poisoned: excluded,
+            conflicts: state.conflicts,
+            reconcile: reconcileStatus(),
+        },
+        monitor: monitor.snapshot({dbFile: dbFile(), reset: false}),
+    };
+    if (isFollower()) {
+        result.master = {url: config.masterUrl(), ...state.master,
+            discovery: state.finder ? state.finder.status() : null};
+    } else {
+        const company = state.company;
+        result.company = company ? {
+            state: company.state,
+            master_terminal_id: company.master_terminal_id,
+            epoch: company.epoch,
+            enabled: company.enabled,
+            is_master: isMasterNow(),
+            polled_at: state.lastModePoll ? new Date(state.lastModePoll).toISOString() : null,
+            error: state.lastModeError,
+        } : null;
+        result.handover = {
+            stage: state.handover.stage,
+            error: state.handover.error,
+            at: state.handover.at,
+        };
+        result.relay = {
+            signal: Boolean(state.signal && state.signal.connected),
+            ready: Boolean(state.signal && state.signal.relayReady),
+        };
+        result.discovery = state.responder
+            ? {port: discovery.settings().port, answering: Boolean(state.responder.socket), answered: state.responder.answered}
+            : null;
+        result.lan = config.isLanFrontEnabled()
+            ? {urls: lanFront.urls(getConfig().port), front: lanFront.status(), devices: lanDevices.status()}
+            : null;
+    }
+    return result;
+};
+
+/**
+ * Для отчёта кассы (ReportService): с какого момента у кассы есть все чеки заведения и можно ли
+ * за более ранним периодом сходить в облако.
+ * from  — позже из двух: начало истории (mirror.historyFrom; неизвестно — «сейчас») и граница
+ *         уборки закрытых чеков (keepClosedDays);
+ * cloud — облачный клиент, только если облако на связи и в нём уже всё, что есть у кассы:
+ *         то же заведение, очередь push пуста. Иначе облачный отчёт был бы неполнее локального.
+ * Без синка — null: облачный контур ядра (pgsql) читает боевую базу, история там вся.
+ */
+const history = (companyId) => {
+    if (!config.isSyncEnabled() || !state.store || !companyId) {
+        return null;
+    }
+    const nowMs = Date.now();
+    const known = mirror.historyFrom(state.store, companyId);
+    const keepFrom = nowMs - config.limits().keepClosedDays * 86400000;
+    const from = new Date(Math.max(known ? known.getTime() : nowMs, keepFrom));
+    const complete = Boolean(state.cloud) && state.online === true && !isFollower()
+        && sessionCompanyId() === companyId && refreshPending() === 0;
+    return {from, cloud: complete ? state.cloud : null, mode: state.mode};
+};
+
+/** Сессия (для ядра: offline-обработчики app.init/ведомый). */
+const session = () => state.session;
+
+const bridge = () => state.bridge;
+
+const store = () => state.store;
+
+module.exports = {
+    start,
+    stop,
+    mode,
+    status,
+    whoami,
+    lanInfo,
+    session,
+    history,
+    bridge,
+    store,
+    setSession,
+    clearSession,
+    logout,
+    resume,
+    wake,
+    relayBroadcast,
+    terminalRequest,
+    isServingAsMaster,
+    // для тестов
+    _state: state,
+    _cycle: cycle,
+    _onLink: onLink,
+    _handleMasterRequest: handleMasterRequest,
+    _pollMode: pollMode,
+    _runReconcile: runReconcile,
+    _heartbeat: heartbeat,
+    _requestSnapshot: requestSnapshot,
+    _runLogout: runLogout,
+};