# Device groups and reviewed rollouts

The company policy is the mandatory baseline. Device groups can add blocked hosts, blocked content, company bookmarks, hidden/locked settings and mandatory document analysis; they can disable downloads, AI and local agents. Groups cannot turn off baseline controls, replace a block list or enable a feature denied by the company policy.

An administrator selects explicit device members. A pilot or expanded rollout selects a nonempty subset of those members; an all-members rollout applies to every selected member. There is no time-based or automatic promotion. Adding members, editing restrictions, changing the cohort and deleting a group are reviewed publication operations. When independent approval is required, the author cannot approve their own operation; the approved hash binds the complete group payload and the expected global generation.

Every publication increases the shared policy version. Each device receives a signed policy with its device ID and effective group IDs; Chromium enforcement, the AI gateway and bookmark mutation endpoints all use that effective policy. Conflict resolution is deterministic: groups are applied in ID order, block/section lists are unions and disabling controls win. Different definitions of the same company bookmark ID cause publication to fail. Group bookmarks cannot collide with the selected devices' personal bookmarks. Oversized merged policies also fail publication.

Policy history stores group configuration at each published generation. Restoring a historical version restores its cohorts and restrictions as a new, reviewed generation; it does not roll device versions backwards. History predating group snapshots is refused when restoring it could silently discard active groups.

## API

- `GET /api/admin/policy-groups`: current version, groups and per-device membership/effective-group/version reports.
- `PUT /api/admin/policy-groups/:id`: `{expectedVersion,group}` where the group contains `id`, `name`, `memberDeviceIds`, `restrictions` and `rollout:{stage,deviceIds}`.
- `DELETE /api/admin/policy-groups/:id`: `{expectedVersion}`.
- `POST /api/admin/policy-groups/preview`: `{deviceId,group?}`; returns the resulting policy, group IDs, baseline diff and current-policy diff without publishing.

Publication and deletion require policy-write authority, or policy-prepare authority when mandatory independent review is enabled. Read and preview require policy-read authority. `202` means queued for review, not applied. Version conflicts return `409`.

## Verification and boundaries

`tests/policy-groups.test.mjs` checks signed pilot/control behavior, promotion, removal, restrictive merge order, review/self-approval/revoked-device failures, permissions, preview, bookmark conflicts, historical restoration and actual gateway/bookmark endpoint enforcement.

Acknowledgment is a device's reported policy version equal to the target version. It is not remote attestation and does not prove endpoint health. The last-seen timestamp is displayed separately. Membership currently uses explicitly enrolled device IDs; dynamic IdP/SCIM department membership, percentage rings, automatic health gates and tenant isolation require further implementation.