viqueue

viqueue는 프라이빗 단일 운영자 dogfood 환경을 위한 미니멀리스트 풀 기반 티켓 보드입니다. 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 및 디바이스 이름을 바인딩하므로 코드 전용 클라이언트는 일회성 코드만 필요합니다. 브라우저는 레거시 nullable 코드에 대한 ID/이름 입력을 유지합니다. 보드는 /v1/devices/me를 확인하고 반환된 자격 증명만 localStorage['viq.deviceCredential']에 저장합니다. 잘못되었거나 취소된 자격 증명은 자동으로 지워지며, 이 디바이스 연결 해제는 서버 측 디바이스를 취소하지 않고 브라우저 로컬 상태만 지웁니다.

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 사용자의 세션은 이를 재사용합니다. 다른 사용자는 그렇지 않습니다. 일반 루트 Pi가 지원되며 루트 전용 파일을 받습니다. 폴링은 해당 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가 이미 존재할 때 설치에는 명시적 오프라인 확인이 필요하며 포인터 변경 전에 커밋된 메인/WAL 상태를 캡처하고 검증하기 위해 SQLite의 백업 API를 사용합니다. 선택적 롤백 복원은 먼저 SQLite 일관 사후 후보 보존 복사본을 생성하고 검증한 다음 데이터베이스를 교체하고 오래된 사이드카를 제거하기 전에 이전 스냅샷을 준비하고 검증합니다. 또한 VIQ_RESTORE_STORAGE=1, VIQ_STORAGE 및 오프라인 확인이 필요합니다. 제거는 런처/포인터를 제거하지만 릴리스 및 백업 증거를 보존합니다. 여기에는 라이브 상태를 게시, 배포 또는 변경하는 것이 없습니다.

viqueue는 Apache License 2.0에 따라 라이선스가 부여됩니다. 제한된 프라이빗 PoC 위협 모델은 SECURITY.md를 참조하세요.