viqueue

viqueue は、プライベートな単一オペレーターのドッグフーディング環境向けの、ミニマルなプルベースのチケットボードです。CLI は viq で、チケット ID は ABC-123 の形式です。v0.4.1 はプレリリースのままであり、本番環境での使用には耐えられません。

ペアリング PoC 契約

HTTP JSON コアが唯一のステートマシンです。認可は意図的に最小限に抑えられています:

• 一度きりの短命なデバイスペアリングコード;

• 固定されたペアリング済みデバイスの種類: coordinator または worker;

• ワーカーの割り当てグループとしてのみ使用される単純なロール。

コーディネーターは、チケットの作成/編集/アーカイブ、ワーカーデバイスまたはロールへの割り当て、提出物への回答/レビュー、ペアリングの発行/失効、ロールの管理を行うことができます。ワーカーは、割り当てられた作業の読み取り、アトミックなクレーム、クレームフェンス付きの進捗/質問/ブロッカー/提出物の投稿、またはクレームの解放を行うことができます。ロールは API 権限を付与しません。

割り当ては起動の承認です。すべての HTTP、CLI、/viq クレームは、同じ述語を呼び出します: アクティブなペアリング済みワーカー、オープンなチケット、正確なデバイス/ロール割り当て、未解決のブロッカーなし、現在のクレームなし。正確なデバイス/ロール割り当てが優先されます。対象となる未割り当てのフリープールチケットも、プロジェクト、ロール、メンバーシップの境界内でアトミックにクレームできます。テイクオーバーは存在しません。Start アクション、保存された Ready 状態、汎用スコープシステム、アクティブな execution_authorities パスはありません。

クレームは、明示的な解放または提出まで、永続的な世代フェンス付きロックのままです。クレームとデバイスの資格情報は、作成/ペアリング時にのみ返され、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、デバイス名をバインドするため、コードのみのクライアントは一度きりのコードだけを必要とします。ブラウザは、レガシーの NULL 許容コード用に ID/名前の入力を保持します。ボードは /v1/devices/me を検証し、返された資格情報のみを localStorage['viq.deviceCredential'] に保存します。無効または失効した資格情報は自動的にクリアされ、Disconnect this device はサーバー側のデバイスを失効させずにブラウザローカルの状態のみをクリアします。

MCP は VIQ_URL と VIQ_DEVICE_TOKEN を使用し、読み取り専用のデバイス/タスク/ステータスビューを公開します。クレームの取得や変更はできません。既存のパッケージをユーザーの Pi プロファイルに pi install <Viq package> でインストールします。その Unix ユーザーの後続の Pi セッションは以下を検出します:

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

/viq PAIRING_CODE はペアリングし、現在の可視 Pi セッションでワーカーを起動します。別個のワーカーコマンドや起動儀式はありません。クレームを試みる前に、現在の Vault で tools/vault-sync/vault-sync sync を可視的に実行し、ステータスがクリーンな CURRENT/EQUAL カノニカルコミットを証明した後にのみクレームします。VIQ サーバーは、唯一の適格性およびアトミッククレームの権限であり、返された完全なチケット契約は、サニタイズされた履歴とともに変更されずに注入されます。viq_submit は再び可視的に同期し、公開が成功した後にのみ、オペレーターの証拠と正確に公開されたコミットを提出します。競合、ガード、またはオフライン障害が発生した場合、フェンスされたクレームは再試行のために保持されます。

ペアリングは、リポジトリ外の ${XDG_CONFIG_HOME:-~/.config}/viq/credential.json に JSON を書き込みます。ディレクトリモードは 0700、ファイルモードは 0600 です。同じ Unix ユーザーのセッションはこれを再利用します。他のユーザーは再利用しません。通常の root Pi がサポートされており、root のみが読み取れるファイルを受け取ります。ポーリングはその Pi セッションが所有するタイマーであり、セッションシャットダウン時に停止し、デーモンや重複したライフサイクルストアはありません。明示的な VIQ_WORKER_LOCKDOWN=1 は、歴史的な分離ワークスペース/ルート拒否の輪郭を維持します。資格情報は、プロンプト、ステータス、ツール結果、argv、環境、リクエストボディに含まれません。信頼された Pi プロセスは、自身の Unix ユーザーのファイルを必然的に読み取ることができます。

正確なワーカーのみのアーカイブは、クリーンなコミット済み HEAD から npm run bundle:worker -- OUTPUT_DIR で構築されます。これには SOURCE_COMMIT、SOURCE_TREE、設定された package.json ディスカバリーパス、およびワーカー拡張機能/ランタイムのみが含まれます。scripts/install-viq-worker.sh は、読み取り専用リリースを作成し、current シンボリックリンクをアトミックに名前変更する前に、明示的な VIQ_WORKER_ROOT、正確な候補コミット、および正確な現在の先行コミットを必要とします。scripts/rollback-viq-worker.sh は、インストールされたその候補と封印された先行コミットのみを受け入れます。VIQ-15 の先行コミットは 1398284ed89a6cf9395f129483f709e63c009286 です。テストとリハーサルは、/opt/viq-worker ではなく、分離されたルートを使用する必要があります。

移行とロールバック

前方移行は devices、pairing_codes、device_roles を作成します。古い execution_authorities テーブルは、以前のビルドへのロールバックを可能にするためにのみ保持されます。候補コードは、それを結合、書き込み、消費、公開しません。インストールには、クライアントを切り替える前にローカルコーディネーターブートストラップが必要です。ロールバックは、以前のバイナリとデータベーススナップショットを一緒に復元します。古いバイナリは保持されたテーブルを引き続き読み取ることができます。

VIQ-15 のカットオーバープリフライトとロールバックは、意図的にテーブル全体の行数を固定しません。チケット、イベント、ロールメンバーシップ、その他の無関係なライブ状態は、レビューとカットオーバーの間に正当に変更される可能性があり、保存する必要があります。グローバルなデータベースの安全性は、代わりに SQLite の整合性、正確なスキーマダイジェスト、認証されたロールバックアーティファクト、およびライター停止後のソース/SQLite 一貫性バックアップのスキーマと数の等価性によって強制されます。調整ヘルパーは、VIQ-15 が変更する正確なクレーム、オープンな質問、アクター、割り当て、タイムスタンプに対して個別にフェイルクローズします。

v0.2 インポーターは明示的なままであり、既存のターゲットを上書きすることはありません。npm run bundle はダーティツリーを拒否し、正確なコミット/ツリー ID を記録し、決定論的なローカルアーカイブを作成します。インストーラーは不変のリリースディレクトリを書き込み、current をアトミックに切り替え、previous を保持します。rollback-local.sh はそれを元に戻します。VIQ_STORAGE が既に存在する場合、インストールには明示的なオフライン確認が必要であり、ポインタ変更の前に SQLite のバックアップ API を使用してコミット済みの main/WAL 状態をキャプチャして検証します。オプションのロールバック復元は、最初に SQLite 一貫性のある候補後保存コピーを作成して検証し、次にデータベースを置き換えて古いサイドカーを削除する前に以前のスナップショットを準備して検証します。同様に VIQ_RESTORE_STORAGE=1、VIQ_STORAGE、およびオフライン確認が必要です。アンインストールはランチャー/ポインタを削除しますが、リリースとバックアップの証拠は保持します。ここでは、ライブ状態を公開、デプロイ、または変更するものはありません。

viqueue は Apache License 2.0 の下でライセンスされています。境界のあるプライベート PoC の脅威モデルについては SECURITY.md を参照してください。