@7365admin1/layer-common 4.149.2 → 4.151.0

package/composables/useSecurityPermission.ts

@@ -575,12 +575,10 @@ export default function useSecurityPermission() {
         description: "Allows the user to delete/remove a unit.",
       },
     },
-    // The strings API-core's HID routes already enforce. `authorizeView` and
-    // `authorizeManage` on every `/api/access-management/hid` route resolve to
-    // core's `utils/hid-access.util.ts` lists -- this family -- so a security
-    // agency that cannot be granted them is refused by the server on every HID
-    // call. Offering them here does not open any gate; it makes the server's
-    // existing rule grantable.
+    // Access cards. Until 2026-10 this family was also what every
+    // `/api/access-management/hid` route read; HID now has `hid-mgmt` below and
+    // the card strings here mean cards again (the server still accepts them
+    // for HID during the alias period, see `useHidAccessPermission`).
     "access-card-mgmt": {
       "see-all-card": {
         check: true,
@@ -590,11 +588,6 @@ export default function useSecurityPermission() {
         check: true,
         description: "Allows the user to view QR tagging.",
       },
-      view: {
-        check: true,
-        description:
-          "Allows the user to view access card management, including HID readers and access logs.",
-      },
       "add-access-card": {
         check: true,
         description: "Allows the user to add a new access card to the system.",
@@ -616,10 +609,37 @@ export default function useSecurityPermission() {
         check: true,
         description: "Allows the user to replace a lost or damaged access card.",
       },
-      "manage-hid": {
+    },
+    // HID access management (decision of 2026-10-16). Five strings under one
+    // resource, mirrored from core `src/utils/hid-access.util.ts`; the HID
+    // screens, menu and buttons (`useHidAccessPermission`) and every
+    // `/api/access-management/hid` route read them. Wildcard passes all five,
+    // an empty list passes none, either manage right implies view.
+    "hid-mgmt": {
+      "use-hid-access": {
+        check: true,
+        description:
+          "Allows the user to see HID Access in the app and use their own QR code, face, PIN, card and intercom at this site.",
+      },
+      "see-all-hid": {
+        check: true,
+        description:
+          "Allows the user to view the site's HID readers, enrolled people, cards and access logs.",
+      },
+      "manage-hid-readers": {
+        check: true,
+        description:
+          "Allows the user to add, configure, test, sync and remove HID readers. Includes viewing.",
+      },
+      "manage-hid-users": {
+        check: true,
+        description:
+          "Allows the user to enrol and remove people, cards and PINs, and assign HID access groups. Includes viewing.",
+      },
+      "manage-hid-settings": {
         check: true,
         description:
-          "Allows the user to manage HID face readers, cards and access records for the site.",
+          "Allows the user to switch HID on or off for the site and configure the HID QR code.",
       },
     },
     // Two resources below are checked ONLY by the iSecure365 mobile app, which

package/composables/useServiceProvider.ts

@@ -19,10 +19,15 @@ export type TSiteProviderMember = {
   unit?: string | null;
   unitName?: string;
   /**
-   * The person's user account. NOT yet returned by the endpoint — the
-   * repository projects it but the service layer drops it. Anything acting on
-   * the PERSON (assigning an access card writes it onto the card as `userId`)
-   * needs this rather than `_id`, which identifies the membership.
+   * The person's user account. Anything acting on the PERSON needs this rather
+   * than `_id`, which identifies the membership: an access card carries it as
+   * `userId`, and HID reader access is bound by it -
+   * `resolvePermissionUserBindings` drops every subject without one.
+   *
+   * Returned from core 3.130. Before that the repository projected it and the
+   * service layer dropped it, so against an older API it is absent on every
+   * row - `providerAccountsKnown` is how the HID enrolment screen tells the two
+   * apart rather than reading an absence as "nobody has an account".
    */
   user?: string | null;
 };

package/constants/permissions.ts

@@ -380,16 +380,38 @@ export const PERMISSIONS = {
     "add-service-provider",
     "invite-service-provider",
   ],
+  // Access cards and QR tagging: the Property Management screens of those
+  // names. Until 2026-10 the HID screens borrowed this family (core
+  // `hid-access.util.ts` read nine of its strings); HID now has `hid-mgmt`
+  // below. `view` and `manage-hid` were only ever HID rights, so they left with
+  // it: see `RETIRED_PERMISSIONS` for how they are still read during the alias
+  // period.
   "access-card-mgmt": [
     "see-all-card",
     "see-all-qr-tagging",
-    "view",
     "add-access-card",
     "update-access-card",
     "replace-access-card",
     "delete-access-card",
     "assign-access-card",
-    "manage-hid",
+  ],
+  // HID access management (decision of 2026-10-16). The five strings are
+  // defined in core `src/utils/hid-access.util.ts` (`HID_RESOURCE` and the
+  // `HID_*_PERMISSIONS` lists); this package does not depend on `@7365admin1/core`,
+  // so it keeps its own copy and `test/hid-access-gate.test.mjs` pins the five.
+  //   use-hid-access       user side: own QR, face, PIN, card, intercom
+  //   see-all-hid          read any HID admin screen
+  //   manage-hid-readers   add, configure, test, sync, remove readers
+  //   manage-hid-users     enrol and remove people, cards, PINs, groups
+  //   manage-hid-settings  HID on or off and the QR configuration for a site
+  // Wildcard passes all five; an empty list passes none; either manage right
+  // implies view. The module deny list key is the resource name.
+  "hid-mgmt": [
+    "use-hid-access",
+    "see-all-hid",
+    "manage-hid-readers",
+    "manage-hid-users",
+    "manage-hid-settings",
   ],
 
   // ---- security ----
@@ -659,12 +681,14 @@ export const LEGACY_PERMISSION_ALIASES: Readonly<
 /**
  * Strings the SERVER enforces that no UI checks and no role editor can grant.
  *
- * `core/src/utils/hid-access.util.ts:36-38` gates the HID Amico visitor
- * endpoints on `visitor:create`, `visitor:update` and `visitor:check-out`. The
- * whole estate spells visitor rights `visitor-mgmt:add-visitor`,
- * `:update-visitor` and so on; a bare `visitor` resource appears in no catalogue
- * in any repo, so no role can hold these and the branch is reachable only
- * through `*` or through the `access-card-mgmt` strings the same list unions in.
+ * `core/src/utils/hid-access.util.ts` keeps `visitor:create`, `visitor:update`
+ * and `visitor:check-out` in `HID_VISITOR_PERMISSIONS` (the visitor pass revoke
+ * routes) until the alias drop. The whole estate spells visitor rights
+ * `visitor-mgmt:add-visitor`, `:update-visitor` and so on; a bare `visitor`
+ * resource appears in no catalogue in any repo, so no role can hold these and
+ * the branch is reachable only through `*`, through
+ * `visitor-mgmt:update-visitor` (which the same list now also accepts) or
+ * through the HID manage users strings it unions in.
  *
  * They are NOT aliased to `visitor-mgmt:*` here, because doing so would be a
  * decision with a real consequence in both directions:
@@ -695,19 +719,47 @@ export const SERVER_ONLY_UNGRANTABLE: readonly string[] = Object.freeze([
  * Canonical strings that are CHECKED -- by this package and by the server -- and
  * that no role editor can GRANT.
  *
- * `NavigationDrawer.vue:172-180` accepts eight `access-card-mgmt` strings for
- * the HID menu and `core/src/utils/hid-access.util.ts:19-32` enforces all nine;
- * only six of them appear in any app's catalogue. The menu still opens, because
- * the gate is an OR and the other six are grantable -- but a role built out of
- * only these three is refused at both ends while looking correctly configured in
- * the role editor. Frozen here so the list cannot grow without somebody noticing.
+ * Empty since 2026-10-16. It used to hold `access-card-mgmt:view`,
+ * `:assign-access-card` and `:manage-hid`, which the HID menu accepted and
+ * `core/src/utils/hid-access.util.ts` enforced while no app's catalogue offered
+ * them. HID now has its own `hid-mgmt` family, offered in full by the property
+ * and security catalogues and as `use-hid-access` by the five service
+ * catalogues (M&E joined on 2026-10-19); `assign-access-card` is offered by
+ * both card catalogues; `view` and `manage-hid` are retired (below). Kept,
+ * and still pinned by the drift test, so the next string of this shape is
+ * recorded here rather than found by somebody staring at a blank screen.
  */
 export const CHECKED_BUT_UNGRANTABLE: readonly TPermissionString[] =
-  Object.freeze([
-    "access-card-mgmt:view",
-    "access-card-mgmt:assign-access-card",
-    "access-card-mgmt:manage-hid",
-  ]);
+  Object.freeze([]);
+
+/**
+ * Strings that are no longer canonical and have no canonical equivalent, but
+ * that this package and the server STILL READ for one release.
+ *
+ * `access-card-mgmt:view` and `access-card-mgmt:manage-hid` were the HID
+ * rights before `hid-mgmt` existed. Core `hid-access.util.ts` keeps them in
+ * `HID_LEGACY_VIEW_PERMISSIONS` and `HID_LEGACY_MANAGE_PERMISSIONS` until the
+ * live roles are backfilled onto the five `hid-mgmt` strings, and
+ * `useHidAccessPermission` reads them at the same levels during that period.
+ * No role editor offers them any more, and nothing new may be written against
+ * them.
+ *
+ * They are NOT legacy aliases: an alias joins two spellings of ONE grant into
+ * an equivalence class (`utils/permission-spellings.ts`) and joins the two
+ * resources into one module spelling group (`utils/org-modules.ts`). Access
+ * cards and HID are two modules, and `manage-hid` meant three HID levels at
+ * once, so neither of those is true here.
+ *
+ * `isKnownPermission` answers true for these; `canonicalPermission` does not
+ * resolve them. The alias drop deletes this list and the composable's legacy
+ * branches together.
+ */
+export const RETIRED_PERMISSIONS: Readonly<Record<string, string>> = Object.freeze({
+  "access-card-mgmt:view":
+    "HID view right before hid-mgmt:see-all-hid; read until the alias drop",
+  "access-card-mgmt:manage-hid":
+    "HID manage right before hid-mgmt:manage-hid-*; read until the alias drop",
+});
 
 const CANONICAL = new Set<string>(PERMISSION_STRINGS);
 
@@ -724,7 +776,7 @@ export function canonicalPermission(
   return LEGACY_PERMISSION_ALIASES[value];
 }
 
-/** Is this string one the catalogue knows, canonical or legacy? */
+/** Is this string one the catalogue knows: canonical, legacy, or retired but still read? */
 export function isKnownPermission(value: string): boolean {
-  return canonicalPermission(value) !== undefined;
+  return canonicalPermission(value) !== undefined || value in RETIRED_PERMISSIONS;
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.149.2",
+  "version": "4.151.0",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "//files": "What a consumer extending this layer actually loads. Without this npm ships the whole working tree - the changesets, the CI workflows, the render harness in tools/ and any scratch directory that happened to exist at publish time. Nuxt resolves a layer by directory, so every runtime directory below has to stay listed; adding a new top-level runtime directory means adding it here too.",

package/pages/[org]/[site]/access-mgmt/hid-qr-code/index.vue

@@ -1,8 +1,11 @@
 <template>
   <v-container fluid>
+    <!-- The member's own pass, so the gate asks for the use right, not the
+         admin view right every other HID page asks for. -->
     <HidEnabledGate
       :site="siteId"
       :org="orgId"
+      level="use"
       message="Enable HID as a service for this site before generating a QR code."
     >
       <HidProfileQrCode :site="siteId" />

package/types/overnight-parking.d.ts

@@ -14,6 +14,20 @@ declare type TOvernightParkingAvailability = {
   sunday: TOvernightParkingDay;
   isAllowPlateNumberOpenBarrier?: boolean;
   autoApproveOvernightParking?: boolean;
+  visitorQrCodes?: TVisitorQrCode[];
+};
+
+declare type TVisitorQrCodeType = "hid" | "entryPass" | "security";
+
+// How long an HID visitor pass lasts: until the end of the visit day, or
+// until the visitor's first entry.
+declare type TVisitorQrUsage = "wholeDay" | "singleUse";
+
+declare type TVisitorQrCode = {
+  type: TVisitorQrCodeType;
+  isEnabled: boolean;
+  // HID only.
+  usage?: TVisitorQrUsage;
 };
 
 declare type TOvernightParkingRequestStatus =

package/types/site.d.ts

@@ -5,7 +5,10 @@ declare type THidQrCodeFormat = "0" | "1" | "2";
 declare type THidPermissionCategory =
   | "resident"
   | "property_management"
-  | "service_provider";
+  /** A provider COMPANY - granting one admits every active member of that org. */
+  | "service_provider"
+  /** ONE PERSON from a provider company, by their membership at this site. */
+  | "service_provider_member";
 
 declare type THidPermissionAssignment = {
   subjectId: string;
@@ -27,7 +30,10 @@ declare type THidSitePermissions = {
   counts: {
     resident: number;
     propertyManagement: number;
+    /** Provider COMPANIES granted. */
     serviceProvider: number;
+    /** Named provider people granted. Counted apart from the companies. */
+    serviceProviderMember: number;
     intercom: number;
   };
 };

package/utils/hid-enrolment-subject.ts

@@ -8,14 +8,20 @@
  * in this repo.
  */
 
-export type HidEnrolmentSubject = "resident" | "property_management";
+/**
+ * What the ENROLLING dropdown offers. Three of these four are the server's own
+ * permission categories; `service_provider_staff` is this screen's own value
+ * and deliberately not one of them - see `subjectLinkOf`.
+ */
+export type HidEnrolmentSubject =
+  | "resident"
+  | "property_management"
+  | "service_provider_staff";
 
 /**
  * The dropdown's options, in the order they are drawn.
  *
- * `title`/`value` because `AppSelect` takes that shape. A service-provider
- * option is expected next; adding it here is most of the work, since the write
- * path already maps `service_provider` onto `serviceProvider`.
+ * `title`/`value` because `AppSelect` takes that shape.
  */
 export const HID_ENROLMENT_SUBJECTS: ReadonlyArray<{
   title: string;
@@ -23,6 +29,7 @@ export const HID_ENROLMENT_SUBJECTS: ReadonlyArray<{
 }> = [
   { title: "Resident", value: "resident" },
   { title: "Member", value: "property_management" },
+  { title: "Service provider", value: "service_provider_staff" },
 ];
 
 /**
@@ -38,6 +45,10 @@ export function subjectCategoryLabel(category: unknown): string {
   const labels: Record<string, string> = {
     resident: "Resident",
     property_management: "Member",
+    // The dropdown's own value: ONE PERSON from a provider company.
+    service_provider_staff: "Service provider",
+    // The server's category, which names a COMPANY. Records in the wild carry
+    // it, and an edit must not call such a row a resident.
     service_provider: "Service provider",
     visitor: "Visitor",
   };
@@ -142,3 +153,214 @@ export function hiddenSubjectNote(count: number, noun: "resident" | "member"): s
   return `${subject} at this site ${verb} not listed:`
     + ` HID enrollment needs an app account, and ${holder} none yet.`;
 }
+
+/* ── THE LINK THAT REACHES THE DEVICE ──────────────────────────────────── */
+
+/**
+ * WHICH SUBJECT FIELD AN ENROLMENT WRITES, and what the identity is called.
+ *
+ * This is the one decision in the dialog that changes who a door lets in, so it
+ * lives here with tests rather than inline in the template's script.
+ *
+ * `service_provider_staff` links through `member`, NOT `serviceProvider`, and
+ * that is the whole design:
+ *
+ * - `serviceProvider` names a `site.service-providers` row, which is a COMPANY.
+ *   `resolvePermissionUserBindings` expands one into every active member of
+ *   that organisation with NO site filter, so granting it puts a 200-person
+ *   firm on a door that eight of them attend.
+ * - A provider employee's membership lives in `members` with `siteId` set to
+ *   this site - `members` carries a unique index on `{org, siteId, user, type}`,
+ *   so it cannot exist there without one. That makes the person site-scoped by
+ *   construction, which is the whole point.
+ *
+ * The identity `type` is `"contractor"` rather than `"staff"`, and it is load
+ * bearing on the server as well as here: core's `permissionSubjectOfIdentity`
+ * reads it to tell a contractor's `member` link from a property-management one,
+ * and files the grant under `service_provider_member` or `property_management`
+ * accordingly. It is also what the Access Permissions tabs filter on.
+ *
+ * An earlier version filed provider staff under `property_management`, since that
+ * category's subject list already accepts these rows. It worked for access and
+ * failed for identity: `permissionIdentityType` derives the identity's type from
+ * the category, so every contractor came back as `staff` - and because the
+ * reconcile rewrites the identity it finds, the `"contractor"` written here was
+ * overwritten seconds later.
+ *
+ * An empty `subjectId` returns `{}` ON PURPOSE. Sending `person: ""` is not
+ * "leave this alone", it is "clear it": the server reads an empty string as the
+ * link being removed and then refuses the write for having no subject at all.
+ */
+export function subjectLinkOf(
+  category: unknown,
+  subjectId: unknown,
+): {
+  person?: string;
+  member?: string;
+  serviceProvider?: string;
+  type?: "resident" | "staff" | "contractor";
+} {
+  const id = String(subjectId ?? "").trim();
+  if (!id) return {};
+  const of = (
+    field: "person" | "member" | "serviceProvider",
+    type: "resident" | "staff" | "contractor",
+  ) => ({
+    person: field === "person" ? id : "",
+    member: field === "member" ? id : "",
+    serviceProvider: field === "serviceProvider" ? id : "",
+    type,
+  });
+  switch (String(category ?? "")) {
+    case "resident":
+      return of("person", "resident");
+    case "service_provider_staff":
+      return of("member", "contractor");
+    case "service_provider":
+      return of("serviceProvider", "contractor");
+    default:
+      return of("member", "staff");
+  }
+}
+
+/**
+ * Which PERMISSION CATEGORY an enrolment's access grant is stored under.
+ *
+ * Mirrors `permissionSubjectOfIdentity` in core, which reads the stored links
+ * rather than this dropdown: a `member` link resolves to `property_management`
+ * whatever the identity's `type` says. Provider staff therefore share the staff
+ * category, which is correct - they are validated against the same subject list
+ * - and the identity `type` is what tells them apart on screen.
+ */
+export function permissionCategoryOf(category: unknown): string {
+  const value = String(category ?? "");
+  if (value === "resident") return "resident";
+  if (value === "service_provider") return "service_provider";
+  if (value === "service_provider_staff") return "service_provider_member";
+  return "property_management";
+}
+
+/**
+ * The dropdown value for a grant's category — the inverse of
+ * `permissionCategoryOf`.
+ *
+ * An edit STATES the subject type rather than offering it, because an identity's
+ * category cannot change after it is created. This is how a stored record is
+ * turned back into the value the form holds, and it is wider than the dropdown on
+ * purpose: records in the wild carry `service_provider`, which names a COMPANY
+ * and which the dropdown does not offer.
+ *
+ * Paired with `subjectOfIdentity` so the mapping lives in one place. `openEdit`
+ * used to repeat the whole links-and-type ternary inline, which is how the copy
+ * in `HidAccessPermissions.vue` was able to go stale without anything noticing.
+ */
+export function enrolmentSubjectOfCategory(category: unknown): string {
+  const value = String(category ?? "");
+  if (value === "resident") return "resident";
+  if (value === "service_provider_member") return "service_provider_staff";
+  if (value === "service_provider") return "service_provider";
+  return "property_management";
+}
+
+/* ── PROVIDER STAFF AS PICKER ROWS ─────────────────────────────────────── */
+
+/**
+ * Can this provider employee be enrolled?
+ *
+ * Two conditions, and both have to be checked here rather than trusted from the
+ * list. An app account, because reader access is bound by user id
+ * (`memberHasAccount`). And an ACTIVE membership: `getProviderMembersBySite`
+ * returns everyone who is not deleted, so a suspended person is in the list the
+ * Members screen draws - marked, deliberately, so the property manager can see
+ * them. Offering a suspended person a door is a different matter.
+ */
+export function providerCanEnrol(
+  row: Record<string, unknown> | null | undefined,
+): boolean {
+  if (!memberHasAccount(row)) return false;
+  return String(row?.status ?? "").trim() === "active";
+}
+
+/**
+ * How a provider employee reads in the picker: their name, their company and
+ * the service beneath it.
+ *
+ * The company comes FIRST in the subtitle. Two contractors with the same first
+ * name are common, and which firm somebody belongs to is what the property
+ * manager actually recognises them by - the service type alone ("Security")
+ * describes half the list.
+ */
+export function providerCandidateOf(row: Record<string, unknown>): {
+  subjectId: string;
+  name: string;
+  subtitle: string;
+} {
+  const text = (value: unknown) => String(value ?? "").trim();
+  const parts = [text(row.company), text(row.typeLabel)].filter(Boolean);
+  return {
+    subjectId: text(row._id),
+    name: text(row.name) || text(row.email) || "Service provider",
+    subtitle: parts.join(" · ") || text(row.role) || text(row.email) || "",
+  };
+}
+
+/**
+ * Does this list tell us who has an app account?
+ *
+ * `GET /api/service-providers/site-members` only began returning `user` in core
+ * 3.130; before that the service layer dropped it even though the repository
+ * projected it. Frontend and backend deploy separately, so this screen can run
+ * against either. Asked of the ROWS rather than of a version number: the key is
+ * present on every row or on none.
+ *
+ * It matters because the answer flips a filter from "cannot be bound to a door"
+ * to "unknown", and a screen that silently reports NOBODY can be enrolled is
+ * worse than one that offers somebody the server then refuses by name.
+ */
+export function providerAccountsKnown(
+  rows: ReadonlyArray<Record<string, unknown>>,
+): boolean {
+  return rows.some((row) => Boolean(row) && typeof row === "object" && "user" in row);
+}
+
+/**
+ * Who may be offered a door, from whatever the endpoint returned.
+ *
+ * With accounts known, both conditions apply (`providerCanEnrol`). Without them,
+ * active membership is all that can be checked here — the server still refuses
+ * anyone it cannot bind, with a message naming them, which is a better failure
+ * than an empty picker.
+ */
+export function providerEnrollableRows<T extends Record<string, unknown>>(
+  rows: ReadonlyArray<T>,
+): T[] {
+  const known = providerAccountsKnown(rows);
+  return rows.filter((row) =>
+    known ? providerCanEnrol(row) : String(row?.status ?? "").trim() === "active",
+  );
+}
+
+/* ── THE SERVICE FILTER'S "ALL" ────────────────────────────────────────── */
+
+/**
+ * WHY "ALL SERVICES" CANNOT BE THE EMPTY STRING HERE.
+ *
+ * `filterProviderMembers` reads an empty `type` as "do not filter", and the
+ * Members screen's own filter uses `value: ""` for All services - but that screen
+ * draws a Vuetify `v-select`, which renders an empty value perfectly well.
+ *
+ * `AppSelect` does not. Its `hasSingleValue` is false for `""`, so the field
+ * falls back to the placeholder, draws in the placeholder's grey, and the option
+ * is never marked as the chosen one in the menu. The filter worked; it just
+ * looked like nothing was selected and like only the real services existed.
+ *
+ * So the option carries a real value here and is translated on the way to the
+ * filter. Changing `AppSelect` instead would touch every one of its callers.
+ */
+export const HID_ALL_SERVICES = "all";
+
+/** The `type` to filter by: "" for All services, the service code otherwise. */
+export function serviceFilterOf(selected: unknown): string {
+  const value = String(selected ?? "").trim();
+  return value === HID_ALL_SERVICES ? "" : value;
+}

package/utils/hid-permission-assignments.ts

@@ -27,11 +27,19 @@
  *    through is a 400.
  */
 
-/** The three real categories. `intercom` is a candidate FILTER, never a category. */
+/**
+ * The real categories. `intercom` is a candidate FILTER, never a category.
+ *
+ * Mirrors `HID_PERMISSION_CATEGORIES` in core, and has to: `seedAssignments`
+ * DROPS a row whose category is not in this list, so a category missing here
+ * silently loses that grant from the edit state - and the save that follows,
+ * being a whole-reader replace, would revoke it.
+ */
 export const HID_PERMISSION_CATEGORIES: THidPermissionCategory[] = [
   "resident",
   "property_management",
   "service_provider",
+  "service_provider_member",
 ];
 
 export type HidAssignmentState = Map<string, { category: THidPermissionCategory; intercom: boolean }>;
@@ -134,11 +142,20 @@ export function applySelection(
 
 /** Per-category totals for the dialog header, counted over the whole reader. */
 export function countByCategory(state: HidAssignmentState): Record<THidPermissionCategory, number> {
-  const counts = { resident: 0, property_management: 0, service_provider: 0 } as Record<
-    THidPermissionCategory,
-    number
-  >;
-  for (const value of state.values()) counts[value.category] += 1;
+  /*
+   * Every category seeded at zero, and the increment guarded.
+   * `counts[category] += 1` on a key this object does not hold yields NaN, so a
+   * category added to the union but missed here would print "NaN" beside a tab
+   * rather than a number. That is exactly what happened when
+   * `service_provider_member` was added.
+   */
+  const counts = HID_PERMISSION_CATEGORIES.reduce(
+    (seeded, category) => ({ ...seeded, [category]: 0 }),
+    {} as Record<THidPermissionCategory, number>,
+  );
+  for (const value of state.values()) {
+    counts[value.category] = (counts[value.category] ?? 0) + 1;
+  }
   return counts;
 }
 
@@ -188,3 +205,55 @@ export function readCandidatePage(response: unknown): {
     pageRange,
   };
 }
+
+/* ── THE SUBJECT AN IDENTITY NAMES ─────────────────────────────────────── */
+
+/**
+ * WHICH GRANT AN ENROLLED PERSON'S ACCESS IS FILED UNDER.
+ *
+ * Mirrors `permissionSubjectOfIdentity` in core, which is the authority. This
+ * repository cannot import it - layer-common does not depend on the core
+ * package - so there is a copy, and the point of putting it HERE is that there
+ * is only one.
+ *
+ * There used to be two: a local `subjectOf` in `HidAccessPermissions.vue` and
+ * the same ternary inline in `HidUserEnrollment.vue`. The first was stale. It
+ * read every `member` link as `property_management`, so granting a contractor
+ * from the permissions screen wrote a staff assignment - and the reconcile then
+ * derived `staff` from that category and rewrote the identity's `type`, moving
+ * the person out of the service-provider tab and into the member one. The
+ * screen for managing contractors reclassified them by being used.
+ *
+ * A `member` link is how BOTH a property-management member and a service
+ * provider's own employee are stored - the person's membership at this site -
+ * so the identity's `type` is the discriminator. `"contractor"` is written by
+ * the enrolment form and re-confirmed by `permissionIdentityType` on every
+ * reconcile, so the two agree instead of one overwriting the other.
+ *
+ * Returns null for a visitor and for an identity linked to nobody. Visitor
+ * access comes from `user_access_rules` rather than a group, so there is nothing
+ * to switch; an identity holding only an account link names no subject to
+ * assign. Both are still DRAWN by the permissions screen, disabled, with a
+ * reason - dropping them silently is what once made the pager say "1-9 of 9"
+ * over seven rows.
+ */
+export function subjectOfIdentity(
+  identity: Record<string, unknown> | null | undefined,
+): { subjectId: string; category: THidPermissionCategory } | null {
+  if (!identity) return null;
+  if (identity.person) {
+    return { subjectId: String(identity.person), category: "resident" };
+  }
+  if (identity.member) {
+    return {
+      subjectId: String(identity.member),
+      category: String(identity.type ?? "") === "contractor"
+        ? "service_provider_member"
+        : "property_management",
+    };
+  }
+  if (identity.serviceProvider) {
+    return { subjectId: String(identity.serviceProvider), category: "service_provider" };
+  }
+  return null;
+}