EvoFirewall/docs/agent-labels.md

Agent labels and materialized assignment

Migration 019_agent_labels.sql adds a bounded label catalog and agent-label join table. Label changes are metadata and do not advance policy generations. Names are unique after NFKC normalization and case folding. Up to 1000 labels may be stored, with at most 20 selected labels per agent.

All API paths use /api/v1:

• GET /agent-labels?limit=20&offset=0, POST /agent-labels {name,color?}, PATCH /agent-labels/:id, DELETE /agent-labels/:id manage the catalog. Maximum page size is 50. Deleting a label removes associations without changing policies.
• GET /agents/:id/labels, PUT /agents/:id/labels {label_ids} read or replace agent labels. Replacement validates every label before writing.
• GET /agents?label_ids=id1,id2 filters by intersection (all specified labels). Empty label filters retain existing fleet behavior. Repeated query parameters are also accepted.
• POST /agent-labels/preview-assignment {selector,mode,set_ids} resolves a concrete target list and returns {mode,total,items:[{agent_id,generation,previous_set_ids,set_ids,changed}]}. The selector must contain either agent_ids (1–100) or label_ids (1–20). Label selection uses intersection and rejects groups larger than 100 instead of truncating. Empty groups can be previewed.
• POST /agent-labels/assign-policy-sets takes the preview request plus expected:[{agent_id,generation}]. The expected IDs must match the currently resolved selection exactly, and every generation must match. Empty assignments, invalid sets, missing agents, pin conflicts or concurrent membership/revision changes fail before any target is changed.

mode:add retains existing assignment order and appends missing selected sets. mode:replace uses the supplied exact set order, including an empty set list. Each final assignment has at most 100 sets through this bulk endpoint. Identical assignments retain the existing generation. The entire materialized operation shares one transaction.

Assignments are one-time changes. Agents that receive a label later do not inherit policies automatically. Label mutations require agents permissions; assignment preview requires policies read and assignment publication requires policies write.

Validation includes atomic invalid-label/set rejection, case-insensitive names, label-only revision preservation, add/replace ordering, unchanged revision behavior, exact membership/revision CAS, pin conflicts, 100/101-agent group boundaries, no subsequent automatic assignment and actual HTTP filtering/RBAC mapping. This does not establish live fleet rollout or production readiness.