Vai al contenuto principale
Hai messo in produzione una policy pii-shield più rigida lunedì, un compagno di squadra ha allargato una regex mercoledì, e ora il traffico reale sta generando falsi positivi. Devi vedere cosa è cambiato, chi l’ha cambiato e fare il rollback — senza indovinare il JSON precedente o ridistribuire nulla. È ciò che il versioning dei guardrail ti dà: una riga di cronologia per modifica, un diff tra due qualsiasi, e revert a un clic. Questa pagina è la landing focalizzata sulla superficie del versioning. Per il motore di guardrail stesso — tipi di regola, stage, azioni — parti dalla panoramica dei Guardrails o dal riferimento Guardrails completo.

​
1. Cosa registra il versioning dei guardrail

Ogni mutazione su un guardrail — create, update, delete e revert — scrive una riga di cronologia append-only nella stessa transazione della modifica. La riga cattura uno snapshot della config visibile all’utente in quel momento:
  • il nome del guardrail,
  • se era abilitato,
  • se era il default del workspace,
  • il corpo completo delle rules.
Ogni riga porta un numero di versione monotono (a partire da 1), l’operazione che l’ha prodotta, l’autore e un timestamp. Poiché la riga è scritta in modo transazionale con la modifica, la cronologia non può mai andare fuori sincrono con la policy attiva — se la modifica esegue il commit, lo fa anche la sua riga di cronologia.
La cronologia è append-only. Un revert non riavvolge né riscrive le righe passate; aggiunge una nuova versione (vedi §4). Vedi sempre la sequenza completa di chi ha fatto cosa, in ordine.

​
2. Un esempio concreto — trova la modifica errata e fai il rollback

Supponi che il guardrail 42 sia andato alla deriva. Scrivi tutto questo dalla console sulla tua sessione — la chiave di relay sk-orca-... serve solo per le chiamate /v1/*, mai per leggere o cambiare la policy.
1

Elenca la cronologia

Apri History sulla riga del guardrail in /console/guardrails. Il feed è dal più recente. Vedi v5 update (mercoledì, da un compagno di squadra), v4 update (lunedì, da te), v3 update, e così via fino a v1 create. Leggere la cronologia è aperto a qualsiasi Member del workspace.
2

Confronta la modifica sospetta

Scegli le due versioni che racchiudono la regressione — v4 e v5 — e visualizza il diff. Il corpo delle rules è mostrato fianco a fianco, così la regex allargata salta fuori come la riga che è cambiata.
3

Revert

Ripristina v4. Il nome del guardrail attivo, il flag enabled, il flag default e le rules sono riportati a quello snapshot, e una nuova riga v6 revert viene aggiunta. La modifica è attiva alla richiesta successiva — nessun redeploy, nessuna modifica all’SDK. Il revert richiede il ruolo Developer+.
Lo stesso flusso sulla REST API, tutto sul tuo session / access token (mai la chiave di relay), con scope a livello di workspace tramite X-Workspace-Id: 
# 1. List versions (Member)
curl https://api.orcarouter.ai/api/guardrail/42/history \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>"

# 2. Diff v4 against v5 (Member) — returns both snapshots to render side by side
curl "https://api.orcarouter.ai/api/guardrail/42/history/diff?from=4&to=5" \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>"

# 3. Revert to v4 — appends a new "revert" version (Developer+)
curl -X POST https://api.orcarouter.ai/api/guardrail/42/revert \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>" \
  -H "Content-Type: application/json" \
  -d '{"to_version": 4}'
La risposta del revert restituisce il guardrail attivo post-revert così che la tua UI possa aggiornarsi senza un round-trip extra. La chiamata /v1/* successiva filtrata da questo guardrail vede la policy ripristinata.

​
3. History, diff e il feed delle versioni

GET /api/guardrail/:id/history restituisce la traccia delle versioni, dalla più recente. Ogni voce è uno snapshot con il suo numero di versione, l’operazione (create / update / delete / revert), l’autore e un timestamp. Il feed ha scope a livello di workspace — un chiamante in un altro workspace ottiene lo stesso envelope not-found di un guardrail mancante, quindi l’esistenza non trapela mai.
GET /api/guardrail/:id/history/:version recupera uno snapshot tramite il suo numero di versione — utile per ispezionare il corpo esatto delle rules che era attivo in un punto nel tempo prima di decidere se ripristinarlo.
GET /api/guardrail/:id/history/diff?from=N&to=M restituisce entrambi gli snapshot — from e to — così che la console possa renderizzare un confronto fianco a fianco di nome, flag e rules. Entrambe le versioni devono appartenere al tuo workspace, altrimenti la chiamata restituisce l’envelope not-found uniforme.
Le letture — elenco di cronologia, singola versione e diff — sono aperte a qualsiasi Member del workspace. Sono pura ispezione: nulla del traffico cambia, e nessuna chiamata a modello o vendor viene effettuata.

​
4. Il revert ripristina come una nuova versione

Un revert non è un riavvolgimento. POST /api/guardrail/:id/revert con un corpo to_version:
  1. Carica lo snapshot della versione target.
  2. Ripristina il nome del guardrail attivo, il flag enabled, il flag default e le rules a quello snapshot — atomicamente, in una transazione.
  3. Aggiunge una nuova riga di cronologia revert che cattura lo stato ora attivo.
Quindi ripristinare v5 indietro a v4 produce una nuova v6 il cui contenuto è uguale a v4. La tua cronologia legge v1 → v2 → … → v5 → v6(revert) — ogni passo preservato, nulla mutato. Ripristina di nuovo quello snapshot più vecchio più tardi e ottieni una v7, e così via.
Uno stato disabilitato o non-default ripristinato fa il round-trip intatto. Se la versione a cui fai il revert aveva enabled: false o non era il default del workspace, il revert riporta il guardrail attivo esattamente a quello — non mantiene silenziosamente la policy attiva. Confronta prima così sai se un revert cambierà anche quei flag.
Poiché il binding vive sul gateway, un revert sposta ogni chiave API collegata a questo guardrail in una volta — e il default del workspace, se è questo — alla chiamata successiva. Vedi collega a una chiave e il default del workspace per come si risolve il collegamento.

​
5. Ruoli e retention

AzioneRottaRuolo
Elenca / leggi versioni, diffGET …/history, …/history/diff, …/history/:versionMember
Revert a una versionePOST …/revertDeveloper+
Tutte le rotte di cronologia sono /api/guardrail/* e si autenticano con il tuo session / access token sotto X-Workspace-Id — mai una chiave di relay sk-orca-.... Il revert porta lo stesso gate Developer+ del creare o aggiornare un guardrail, dato che cambia il traffico reale.
La cronologia è conservata alle 50 versioni più recenti per guardrail. Le righe più vecchie sono potate automaticamente man mano che continui a modificare, così un workflow di edit-loop chiacchierone non fa mai crescere la traccia all’infinito. L’endpoint di elenco restituisce fino alle 50 più recenti, dalla più recente.
Abbina il versioning al tuning flag-first: metti in produzione una nuova regola come flag, osserva il feed dei matches, e se si comporta male, confronta e fai il revert in secondi invece di ricostruire la vecchia policy a mano.

​
6. Dove andare dopo

Test ed eval prima di mettere in produzione

Dimostra una policy nella sandbox e contro un corpus prima che diventi una versione che dovresti ripristinare.

Tuning dei falsi positivi

Il loop flag-poi-promuovi che il versioning rende sicuro.

Azioni: block, mask, flag

Cosa fa ogni regola una volta che una versione è attiva.

Riferimento Guardrails

Il motore completo — tipi di regola, stage, preset e l’API completa.
Il versioning qui copre la content policy del guardrail. Il firewall ha la sua superficie di modifica per la policy di tool; per come i due layer di enforcement differiscono, vedi guardrails vs. firewall.