Groups

Implementation status

Built end to end: the principal kind of group (principal_group plus membership, group-targeted grants via principal_grant.group_id, the effective-grant union in the loader, /principal-groups CRUD gated by principal_group:*, the :rename custom method, and the console Groups pages), as a grant subject only (see below).

A group is a named set of entities cutting across the structural trees: the tree handles config by position and kind, groups by attribute or hand-picked set (“all AV displays”). One primitive serves two jobs, a cascade overlay and an access scope, which an anonymous predicate never could.

What a group is

The general group table, tracked in #10

A group:

• is component / system / location / principal kind;
• has static membership (an explicit list) or dynamic membership (a filter, re-evaluated live, so a device leaves the moment it stops matching);
• has a weight, its specificity on the shared scale (see Placement; the only weights in the system);
• carries variable / tag / rule bindings, with the same per-kind combinators the cascade uses;
• is also the unit of access control: a visibility / permission scope (identity and access).

The general group table carries the id, kind, membership, and weight.

What is built is the principal arm: principal_group and its membership, a grant subject (grants attach to the group and reach its members), not an access scope (scope_kind='group' is refused today with a 422).

A group’s name is an ordinary entity name (^[a-z0-9][a-z0-9-]*$, 100 characters, a uuid refused), enforced by the Storage Gateway on create and on rename rather than by the request schema alone (ADR-0077). Moving it is the :rename custom method, POST /principal-groups/{id}:rename gated by principal_group:rename; the PATCH body does not carry a name at all (ADR-0076). The whole collection is addressed by the uuid, so a group is the one case where the rename route takes an {id} rather than the name it is about to move; nothing inside the platform notices, since membership and grants both key on that uuid.

principal_group (identity): generated from the migrated schema by make gen

Column	Type	Constraints
id	uuid	PK, default uuidv7()
name	text	not null
label	text
description	text
created_at	timestamp with time zone	not null, default now()
updated_at	timestamp with time zone	not null, default now()

CHECK constraints and unique indexes on principal_group

• principal_group_name_key: CREATE UNIQUE INDEX principal_group_name_key ON public.principal_group USING btree (name)

principal_group_member (identity): generated from the migrated schema by make gen

Column	Type	Constraints
group_id	uuid	PK, FK → principal_group.id
principal_id	uuid	PK, FK → principal.id
created_at	timestamp with time zone	not null, default now()

Entity groups on the cascade: weights, dynamic membership, and group-as-scope, tracked in #10

Placement: one specificity scale

A group is placed on the cascade’s one specificity scale by its weight: a high weight sits above deployment (a must-apply override), a low weight below it. The scale, the segmented precedence key, and the worked example are stated once, on cascade.

Multiple membership

An entity belongs to a flat set of groups, no second precedence axis: their bindings fold by weight on the one shared scale, and the resolve view names the winner.

No nesting

Groups do not contain groups: a dynamic filter already expresses a union (type in (codec, display)) and multiple membership covers the rest, so nesting would earn only a narrow “DRY union of static sets” case, not worth its transitive-membership and cycle-guard cost. An open question, gated on that case actually biting.

Types are not layers

A _type (device/app, AV-System, room) is a classification attribute, never a tree position: author a dynamic group filtered on type (type == X) and place it by weight (cascade).

What groups are for

The group-specific operator stories:

• A fleet-wide fix that auto-clears. A dynamic group model == "Room Kit Pro" && firmware < "11.5" at high weight slows the poll and suppresses the false high-memory alarm; the affected codecs get it at once, and each drops out the moment it upgrades. (dynamic group above deployment, live membership, rule suppression)
• A broad policy as a floor, not a ceiling. Baseline stricter thresholds on a low-weight “PCI-scope” group, so a lab that needs its own values still wins. (low-weight group below deployment)
• A hand-picked set no filter can name. The executive briefing rooms in a static “Exec Rooms” group for premium escalation, with the exec-support team granted visibility to that same group. (static membership; groups double as the access scope)