viqueue

viqueue ist ein minimalistisches Pull-basiertes Ticket-Board für eine private Einzelbetreiber-Dogfood-Umgebung. Die CLI ist viq; Ticket-IDs sehen aus wie ABC-123. v0.4.1 bleibt eine Vorabversion und ist nicht produktionsreif.

Pairing-PoC-Vertrag

Der HTTP-JSON-Kern ist die einzige Zustandsmaschine. Die Autorisierung ist bewusst klein:

• einmalige, kurzlebige Geräte-Pairing-Codes;

• feste gepaarte Geräteart: coordinator oder worker;

• einfache Rollen, die nur als Arbeitszuweisungsgruppen verwendet werden.

Ein Koordinator kann Tickets erstellen/bearbeiten/archivieren, einem Worker-Gerät oder einer Rolle zuweisen, Einreichungen beantworten/prüfen, Pairing ausstellen/widerrufen und Rollen verwalten. Ein Worker kann zugewiesene Arbeit lesen, sie atomar beanspruchen, Claim-geschützte Fortschritte/Fragen/Blocker/Einreichungen posten oder seinen Claim freigeben. Rollen gewähren keine API-Berechtigungen.

Zuweisung ist Startautorisierung. Jeder HTTP-, CLI- und /viq-Claim ruft dasselbe Prädikat auf: aktiver gepaarter Worker, offenes Ticket, exakte Geräte-/Rollenzuweisung, kein ungelöster Blocker und kein aktueller Claim. Exakte Geräte-/Rollenzuweisungen werden bevorzugt; berechtigte nicht zugewiesene Free-Pool-Tickets können ebenfalls atomar innerhalb von Projekt-, Rollen- und Mitgliedschaftsgrenzen beansprucht werden. Übernahme ist nicht vorhanden. Es gibt keine Start-Aktion, keinen gespeicherten Ready-Zustand, kein generisches Bereichssystem und keinen aktiven execution_authorities-Pfad.

Claims bleiben dauerhafte, generationsgeschützte Sperren bis zur expliziten Freigabe oder Einreichung. Claim- und Geräteanmeldeinformationen werden nur bei Erstellung/Pairing zurückgegeben, als Hash in SQLite gespeichert und niemals in Ticket-/Modellkontext aufgenommen.

Related MCP server: Ticket API MCP Server

Bootstrap und Ausführung

Erfordert 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 ist eine lokale Installationsaktion und gibt die erste Koordinator-Anmeldeinformation einmalig aus. Stellen Sie eine Anmeldeinformation mit --device-token oder VIQ_DEVICE_TOKEN bereit:

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

Das Browser-Board zeigt ein Pairing-Formular, wenn keine gültige lokale Pairing-Konfiguration vorhanden ist. Neu vom Koordinator ausgestellte Codes binden Akteur, Art, Geräte-ID und Gerätename, sodass reine Code-Clients nur den einmaligen Code benötigen; der Browser behält ID/Name-Eingaben für veraltete nullable Codes bei. Das Board verifiziert /v1/devices/me und speichert nur die zurückgegebene Anmeldeinformation in localStorage['viq.deviceCredential']. Ungültige/widerrufene Anmeldeinformationen werden automatisch gelöscht, und Dieses Gerät trennen löscht nur den Browser-lokalen Zustand, ohne das serverseitige Gerät zu widerrufen.

MCP verwendet VIQ_URL und VIQ_DEVICE_TOKEN und stellt schreibgeschützte Geräte-/Aufgaben-/Statusansichten bereit; es kann keine Claims erwerben oder mutieren. Installieren Sie das vorhandene Paket im Pi-Profil eines Benutzers mit pi install <Viq-Paket>. Nachfolgende Pi-Sitzungen für diesen Unix-Benutzer erkennen:

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

/viq PAIRING_CODE paart und startet den Worker in der aktuellen sichtbaren Pi-Sitzung; es gibt keinen separaten Worker-Befehl oder Startritual. Vor jedem Claim-Versuch führt es sichtbar tools/vault-sync/vault-sync sync im aktuellen Vault aus und beansprucht nur, nachdem der Status einen sauberen CURRENT/EQUAL-kanonischen Commit beweist. Der VIQ-Server bleibt die einzige Berechtigungs- und atomare Claim-Autorität, und der vollständige zurückgegebene Ticketvertrag wird unverändert mit bereinigter Historie injiziert. viq_submit synchronisiert sichtbar erneut und reicht die Operator-Evidenz plus den exakten veröffentlichten Commit erst ein, nachdem die Veröffentlichung erfolgreich war; Konflikt-, Schutz- oder Offline-Fehler behält den fenced Claim für einen erneuten Versuch.

Pairing schreibt JSON außerhalb von Repositories unter ${XDG_CONFIG_HOME:-~/.config}/viq/credential.json, mit Verzeichnismodus 0700 und Dateimodus 0600. Sitzungen für denselben Unix-Benutzer verwenden es erneut; andere Benutzer nicht. Gewöhnliches Root-Pi wird unterstützt und erhält eine nur für Root zugängliche Datei. Polling ist ein Timer, der dieser Pi-Sitzung gehört und beim Herunterfahren der Sitzung gestoppt wird, ohne Daemon oder doppelten Lebenszyklus-Speicher. Explizites VIQ_WORKER_LOCKDOWN=1 bewahrt das historische isolierte-Arbeitsbereich/Root-Verweigerungsprofil. Anmeldeinformationen bleiben aus Eingabeaufforderungen, Status, Tool-Ergebnissen, argv, Umgebung und Anforderungstexten heraus; der vertrauenswürdige Pi-Prozess kann notwendigerweise die Datei seines eigenen Unix-Benutzers lesen.

Ein exaktes Worker-only-Archiv wird aus sauberem committetem HEAD mit npm run bundle:worker -- OUTPUT_DIR erstellt. Es enthält SOURCE_COMMIT, SOURCE_TREE, den konfigurierten package.json-Erkennungspfad und nur die Worker-Erweiterung/Laufzeit. scripts/install-viq-worker.sh erfordert ein explizites VIQ_WORKER_ROOT, einen exakten Kandidaten-Commit und einen exakten aktuellen Vorgänger, bevor es ein schreibgeschütztes Release erstellt und den current-Symlink atomar umbenennt. scripts/rollback-viq-worker.sh akzeptiert nur diesen installierten Kandidaten und den versiegelten Vorgänger; der VIQ-15-Vorgänger ist 1398284ed89a6cf9395f129483f709e63c009286. Tests und Proben müssen ein isoliertes Root verwenden, niemals /opt/viq-worker.

Migration und Rollback

Die Vorwärtsmigration erstellt devices, pairing_codes und device_roles. Die alte execution_authorities-Tabelle wird nur beibehalten, damit ein Rollback auf den früheren Build möglich bleibt; Kandidatencode verbindet, schreibt, konsumiert oder exponiert sie weder. Die Installation erfordert einen lokalen Koordinator-Bootstrap, bevor Clients umgestellt werden. Rollback stellt das vorherige Binärprogramm und den Datenbanksnapshot zusammen wieder her; alte Binärprogramme können ihre beibehaltene Tabelle weiterhin lesen.

Der VIQ-15-Cutover-Preflight und das Rollback beabsichtigen bewusst nicht, ganze Tabellenzeilenanzahlen zu fixieren. Tickets, Ereignisse, Rollenmitgliedschaften und anderer unabhängiger Live-Zustand können sich zwischen Überprüfung und Cutover legitimerweise ändern und müssen erhalten bleiben. Die globale Datenbanksicherheit wird stattdessen durch SQLite-Integrität, den exakten Schema-Digest, authentifizierte Rollback-Artefakte und Quell-/SQLite-konsistente Backup-Schema-und-Anzahl-Gleichheit nach dem Stoppen der Schreiber durchgesetzt. Das Reconciliations-Hilfsprogramm schlägt separat auf die exakten Claims, offenen Fragen, Akteure, Zuweisungen und Zeitstempel fehl, die VIQ-15 ändert.

Der v0.2-Importer bleibt explizit und überschreibt niemals ein vorhandenes Ziel. npm run bundle verweigert einen unsauberen Baum, zeichnet exakte Commit-/Baumidentität auf und erstellt ein deterministisches lokales Archiv. Der Installer schreibt ein unveränderliches Release-Verzeichnis und schaltet current atomar um, wobei previous erhalten bleibt; rollback-local.sh schaltet es zurück. Wenn VIQ_STORAGE bereits existiert, erfordert die Installation eine explizite Offline-Bestätigung und verwendet die SQLite-Backup-API, um den committeten Main-/WAL-Zustand vor jeder Zeigeränderung zu erfassen und zu validieren. Optionale Rollback-Wiederherstellung erstellt und validiert zuerst eine SQLite-konsistente Post-Kandidaten-Erhaltungskopie, bereitet dann den vorherigen Snapshot vor und validiert ihn, bevor sie die Datenbank ersetzt und veraltete Sidecars entfernt; sie erfordert ebenfalls VIQ_RESTORE_STORAGE=1, VIQ_STORAGE und Offline-Bestätigung. Deinstallation entfernt Launcher/Zeiger, bewahrt aber Release- und Backup-Evidenz. Nichts davon veröffentlicht, deployt oder mutiert Live-Zustand.

viqueue ist unter der Apache License 2.0 lizenziert. Siehe SECURITY.md für das begrenzte private-PoC-Bedrohungsmodell.