Policy rollouts

Feedback, immutable policy revisions, replay results, promotions, and rollbacks are timeline events in the local WAL. A standalone node retains this history without SpacetimeDB or another control-plane database.

The lifecycle

draft → shadow → canary → active
                         ↓
             older active revision ← rollback

Create a revision with POST /v1/runs/:id/policies. The response’s revision is the sequence of the durable creation event. The next revision must include that value as parent_revision. A stale parent receives 409 Conflict.

Promotions use POST /v1/runs/:id/policies/:revision/activate. Shadow and canary are replay-only stages in this release. They record the operator decision without mutating the live media worker. On a live WHIP run, active promotion requires the current expected_generation. The API sends prompt and schema through the bounded session command channel and records an acknowledgement only after the owning VLM worker accepts it. A closed or replaced generation rejects the request.

Restricted-zone parameters are constructed when a pipeline generation starts. They are preserved in the revision and available for replay, but a live response lists parameters.restricted_zone in deferred_fields until a new generation starts. This avoids claiming that a threshold changed while an older detector is still running.

Candidate replay

POST /v1/runs/:id/policies/:revision/replay reads restricted_zone_activity_entered events already persisted on the run. It compares their recorded confidence with the revision’s enter_motion_score and reports accepted, rejected, and missing-score counts.

Replay shows how a revised threshold treats candidates that the original pipeline captured. Missed incidents and behavior on another camera require retained source media and labelled evaluation data.

Operator feedback

POST /v1/runs/:id/feedback commits operator_feedback_submitted before returning success. GET /v1/feedback reconstructs entries from the local WAL and filters them to caller-owned runs. When SpacetimeDB is configured, it receives a best-effort mirror after the local commit. Collection and review still use the local WAL.

See the API reference for request and response fields.