viqueue

viqueue — это минималистичная доска задач на основе pull-модели для частной среды dogfood с одним оператором. CLI — viq; идентификаторы задач выглядят как ABC-123. v0.4.1 остаётся предварительным выпуском и не готов к продакшену.

Контракт PoC сопряжения

Ядро HTTP JSON — единственный конечный автомат. Авторизация намеренно минимальна:

• одноразовые короткоживущие коды сопряжения устройств;

• фиксированный тип сопряжённого устройства: coordinator или worker;

• простые роли, используемые только как группы назначения для работников.

Координатор может создавать/редактировать/архивировать задачи, назначать их на устройство работника или роль, отвечать/проверять отправленные результаты, выдавать/отзывать сопряжение и управлять ролями. Работник может читать назначенную работу, атомарно забирать её (claim), отправлять прогресс/вопросы/блокеры/результаты, ограниченные claim-ом, или освобождать свой claim. Роли не дают никаких разрешений API.

Назначение — это авторизация запуска. Каждый claim через HTTP, CLI и /viq вызывает один и тот же предикат: активный сопряжённый работник, открытая задача, точное назначение на устройство/роль, отсутствие нерешённых блокеров и отсутствие текущего claim. Точные назначения на устройство/роль предпочтительны; подходящие неназначенные задачи из свободного пула также могут быть атомарно заявлены в пределах проекта, роли и членства. Захват (takeover) отсутствует. Нет действия Start, сохранённого состояния Ready, общей системы областей (scope) или активного пути execution_authorities.

Claims остаются долговечными блокировками с защитой поколений (generation-fenced) до явного освобождения или отправки. Учётные данные claim и устройства возвращаются только при создании/сопряжении, хранятся в виде хэша в SQLite и никогда не включаются в контекст задачи/модели.

Related MCP server: Ticket API MCP Server

Инициализация и запуск

Требуется Node.js 22.

npm test
npm run build
viq-bootstrap --storage ./data/viqueue.sqlite --id coord --name "Coordinator"
node dist/src/server.js --storage=./data/viqueue.sqlite

viq-bootstrap — это локальное действие установки, которое однократно выводит первое учётное данное координатора. Укажите учётное данное с помощью --device-token или VIQ_DEVICE_TOKEN:

viq project create ABC --device-token COORDINATOR_CREDENTIAL
viq device pair-code --kind worker --device-token COORDINATOR_CREDENTIAL
viq role create tower-pi --name "Tower Pi" --device-token COORDINATOR_CREDENTIAL
viq role grant tower-worker tower-pi --device-token COORDINATOR_CREDENTIAL
viq ticket create ABC "Fix parser" --assignee-role tower-pi --device-token COORDINATOR_CREDENTIAL
viq ticket claim-next --project ABC --device-token WORKER_CREDENTIAL

Браузерная доска показывает форму сопряжения, когда нет действующего локального сопряжения. Новые коды, выпущенные координатором, связывают актора, тип, идентификатор устройства и имя устройства, поэтому клиентам, использующим только код, нужен только одноразовый код; браузер сохраняет поля ID/имени для устаревших nullable-кодов. Доска проверяет /v1/devices/me и сохраняет только возвращённое учётное данное в localStorage['viq.deviceCredential']. Недействительные или отозванные учётные данные очищаются автоматически, а Disconnect this device очищает только локальное состояние браузера, не отзывая серверное устройство.

MCP использует VIQ_URL и VIQ_DEVICE_TOKEN и предоставляет доступные только для чтения представления устройств/задач/статусов; он не может получать или изменять claims. Установите существующий пакет в профиль Pi пользователя с помощью pi install <Viq package>. Последующие сеансы Pi для этого пользователя Unix обнаруживают:

/viq PAIRING_CODE [--project KEY]
/viq status
/viq pause|resume|stop

/viq PAIRING_CODE выполняет сопряжение и запускает работника в текущем видимом сеансе Pi; отдельной команды работника или ритуала запуска нет. Перед каждой попыткой claim он видимо запускает tools/vault-sync/vault-sync sync в текущем Vault и выполняет claim только после того, как статус подтвердит чистый канонический коммит CURRENT/EQUAL. Сервер VIQ остаётся единственным органом определения права и атомарного claim, а полный возвращённый контракт задачи внедряется без изменений с очищенной историей. viq_submit видимо синхронизируется снова и отправляет доказательства оператора и точный опубликованный коммит только после успешной публикации; конфликт, защита или сбой в офлайне сохраняют защищённый claim для повторной попытки.

Сопряжение записывает JSON вне репозиториев в ${XDG_CONFIG_HOME:-~/.config}/viq/credential.json с режимом каталога 0700 и режимом файла 0600. Сеансы для того же пользователя Unix повторно используют его; другие пользователи — нет. Обычный root Pi поддерживается и получает файл, доступный только root. Опрос — это таймер, принадлежащий этому сеансу Pi, останавливаемый при завершении сеанса, без демона или дублирующего хранилища жизненного цикла. Явный VIQ_WORKER_LOCKDOWN=1 сохраняет исторический контур изолированного рабочего пространства/отказа root. Учётные данные не попадают в подсказки, статус, результаты инструментов, argv, окружение и тела запросов; доверенный процесс Pi, естественно, может читать файл своего собственного пользователя Unix.

Точный архив только для работника создаётся из чистого закоммиченного HEAD с помощью npm run bundle:worker -- OUTPUT_DIR. Он включает SOURCE_COMMIT, SOURCE_TREE, настроенный путь обнаружения package.json и только расширение/рантайм работника. scripts/install-viq-worker.sh требует явный VIQ_WORKER_ROOT, точный коммит-кандидат и точного текущего предшественника, прежде чем создаст read-only релиз и атомарно переименует симлинк current. scripts/rollback-viq-worker.sh принимает только этот установленный кандидат и запечатанного предшественника; предшественник VIQ-15 — 1398284ed89a6cf9395f129483f709e63c009286. Тесты и репетиции должны использовать изолированный корень, никогда не /opt/viq-worker.

Миграция и откат

Прямая миграция создаёт devices, pairing_codes и device_roles. Старая таблица execution_authorities сохраняется только для того, чтобы оставался возможен откат к более ранней сборке; код-кандидат не присоединяется к ней, не пишет, не потребляет и не раскрывает её. Установка требует локальной начальной настройки координатора перед переключением клиентов. Откат восстанавливает предыдущий бинарный файл и снимок базы данных вместе; старые бинарные файлы по-прежнему могут читать свою сохранённую таблицу.

Предварительная проверка перехода и откат VIQ-15 намеренно не фиксируют количество строк во всей таблице. Задачи, события, членство в ролях и другое несвязанное живое состояние могут легитимно меняться между проверкой и переходом и должны быть сохранены. Глобальная безопасность базы данных вместо этого обеспечивается целостностью SQLite, точным дайджестом схемы, аутентифицированными артефактами отката и равенством схемы и количества в согласованной резервной копии исходного кода/SQLite после остановки писателей. Вспомогательный инструмент сверки отдельно завершается с ошибкой (fail closed) по точным claims, открытым вопросам, акторам, назначениям и временным меткам, которые изменяет VIQ-15.

Импортёр v0.2 остаётся явным и никогда не перезаписывает существующую цель. npm run bundle отказывается от грязного дерева, записывает точную идентичность коммита/дерева и создаёт детерминированный локальный архив. Установщик записывает неизменяемый каталог релиза и атомарно переключает current, сохраняя previous; rollback-local.sh переключает его обратно. Когда VIQ_STORAGE уже существует, установка требует явного подтверждения в офлайне и использует API резервного копирования SQLite для захвата и проверки закоммиченного состояния main/WAL перед любым изменением указателя. Необязательное восстановление при откате сначала создаёт и проверяет согласованную с SQLite копию сохранения после кандидата, затем подготавливает и проверяет предыдущий снимок перед заменой базы данных и удалением устаревших боковых файлов; оно также требует VIQ_RESTORE_STORAGE=1, VIQ_STORAGE и подтверждения в офлайне. Удаление убирает лаунчеры/указатели, но сохраняет релиз и резервные копии. Ничто здесь не публикует, не развёртывает и не изменяет живое состояние.

viqueue распространяется под лицензией Apache License 2.0. См. SECURITY.md с описанием ограниченной модели угроз для частного PoC.