@jwilleke/ngdpbase-types 5.27.0 → 5.28.0

package/lib/packages/ngdpbase-types/index.d.ts

@@ -36,9 +36,12 @@ export type { PageAction } from '../../src/utils/pageUrl.js';
 export type { default as ConsentManager, ConsentScopeStatus } from '../../src/managers/ConsentManager.js';
 export type { AddonConsentRegistration, ConsentDocument, ConsentRecord, ConsentRequiredError, ConsentScope, ConsentSeen, ConsentStatus } from '../../src/types/Consent.js';
 export type { default as ImportManager } from '../../src/managers/ImportManager.js';
-export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceUpload, IceSource, IceRunRequest, IceRunReport, IceFileReport, IceFileStatus } from '../../src/ice/types.js';
+export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, IceUpload, IceSource, IceRunRequest, IceRunReport, IceFileReport, IceFileStatus } from '../../src/ice/types.js';
+export type { default as UserManager, UserUpdateInput, UserUpdateFn } from '../../src/managers/UserManager.js';
+export type { User, UserPreferences } from '../../src/types/User.js';
 export type { default as PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
 export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
 export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';
 export type { Organization, OrganizationInput, OrganizationUpdate } from '../../src/types/Organization.js';
 export type { ContactRefusedError } from '../../src/utils/contactAccess.js';
+export type { default as RoleManager } from '../../src/managers/RoleManager.js';

package/lib/src/context/ActorContext.d.ts

@@ -13,8 +13,8 @@
  * the call arrived under, and the address it came from. What does not: roles.
  * Authority is resolved at the moment of each decision, never carried.
  */
-import type { PermissionSubject } from '../managers/UserManager.js';
-import type { JobContext } from './JobContext.js';
+import type { PermissionSubject, JobSubject } from '../managers/UserManager.js';
+import { type JobContext } from './JobContext.js';
 export type ActorContext = PermissionSubject | JobContext;
 /**
  * The fields an audit record takes from a context.
@@ -35,6 +35,19 @@ export interface ActorAttribution {
     metadata: Record<string, unknown>;
 }
 export declare function isJobContext(ctx: ActorContext): ctx is JobContext;
+/**
+ * The one place a context becomes the subject a decision reads (#2022).
+ *
+ * Called by the deciders — `PolicyDecisionPoint` (`decide`, `permits`,
+ * `holds`) and `PolicyInformationPoint`'s page questions — and by nobody
+ * else: a caller hands them its context as given. A `JobContext` carries
+ * identity, never authority, so it becomes a `JobSubject` whose roles policy
+ * resolves now, keeping its token, share and proxy claims
+ * (`toPermissionSubject`). Anything else is already a subject and passes
+ * through. The object guard is #1173's: `'x' in 'jim'` throws. Not part of
+ * the add-on API; `npm run lint:context` holds callers to it.
+ */
+export declare function decisionSubject<S extends PermissionSubject | JobSubject>(input: ActorContext | S | null | undefined): PermissionSubject | JobSubject | S | null | undefined;
 /**
  * Who acted, for the record — read from the context, never guessed.
  *

package/lib/src/context/ActorContext.js

@@ -1,8 +1,28 @@
+import { toPermissionSubject } from './JobContext.js';
 import { attributedTo } from './bootActions.js';
 import { proxyAttribution } from '../utils/proxyClaim.js';
 export function isJobContext(ctx) {
     return 'origin' in ctx && 'requestedAt' in ctx;
 }
+/**
+ * The one place a context becomes the subject a decision reads (#2022).
+ *
+ * Called by the deciders — `PolicyDecisionPoint` (`decide`, `permits`,
+ * `holds`) and `PolicyInformationPoint`'s page questions — and by nobody
+ * else: a caller hands them its context as given. A `JobContext` carries
+ * identity, never authority, so it becomes a `JobSubject` whose roles policy
+ * resolves now, keeping its token, share and proxy claims
+ * (`toPermissionSubject`). Anything else is already a subject and passes
+ * through. The object guard is #1173's: `'x' in 'jim'` throws. Not part of
+ * the add-on API; `npm run lint:context` holds callers to it.
+ */
+export function decisionSubject(input) {
+    if (typeof input !== 'object' || input === null)
+        return input;
+    // A JobSubject is not an ActorContext, and is not a job context either.
+    const ctx = input;
+    return isJobContext(ctx) ? toPermissionSubject(ctx) : input;
+}
 /**
  * Who acted, for the record — read from the context, never guessed.
  *

package/lib/src/ice/types.d.ts

@@ -121,6 +121,16 @@ export interface RegisteredShim extends IceShim {
 }
 /** D11: what the person importing chose to do with the original file. */
 export type OriginalChoice = 'cite' | 'keep' | 'none';
+/**
+ * D11: the original-file choices a receiver offers, and which one is chosen
+ * when the user picks none (#2021). The import screen offers only `allowed`,
+ * and the engine refuses a run asking for any other.
+ */
+export interface IceOriginalChoices {
+    allowed: OriginalChoice[];
+    /** One of `allowed`. Default: `ngdpbase.import.engine.default-original` when allowed, else the first allowed. */
+    default?: OriginalChoice;
+}
 /** A citation to the origin (D11): the receiver renders it, as a footnote on a page. */
 export interface IceCitation {
     name: string;
@@ -172,6 +182,8 @@ export interface IceReceiver {
      * store). Without this, `keep` hands the original to the files receiver.
      */
     keepOriginal?(original: IceItem, ctx: ActorContext): Promise<ReceiveOutcome>;
+    /** The original-file choices this receiver offers (D11). Without it: all three. */
+    originals?: IceOriginalChoices;
 }
 export interface RegisteredReceiver extends IceReceiver {
     id: string;
@@ -238,6 +250,14 @@ export interface IceRunReport {
     error?: string;
     files: IceFileReport[];
 }
+/**
+ * A kept original as the ledger remembers it, with the door that kept it
+ * (a receiver's own `keepOriginal`, or `core.files`). A later run of the same
+ * fingerprint through the same door reuses it instead of keeping another copy.
+ */
+export interface LedgerOriginal extends KeptOriginal {
+    door: string;
+}
 /** What the engine remembers about one file in a scope. */
 export interface LedgerFileEntry {
     name: string;
@@ -247,6 +267,8 @@ export interface LedgerFileEntry {
     message?: string;
     at: string;
     refs: string[];
+    /** The original kept for this fingerprint, whatever became of the conversion (D11). */
+    original?: LedgerOriginal;
 }
 /**
  * Where the engine keeps fingerprints, per-file status and item keys, per

package/lib/src/managers/AddonsManager.d.ts

@@ -121,8 +121,12 @@ export interface AddonModule {
      * "section was not rendered at all" (addon disabled mid-session, cached
      * form). Without it, absent checkbox fields look identical to "user
      * submitted no such field" and you may silently clobber stored values.
+     *
+     * `ctx` is the signed-in user's own context, forwarded from the request:
+     * pass it to your manager's door (and to the PDP) instead of rebuilding a
+     * subject from `user` (#2018).
      */
-    profileSection?(user: AddonProfileUser): Promise<AddonProfileSection | null> | AddonProfileSection | null;
+    profileSection?(user: AddonProfileUser, ctx: ActorContext): Promise<AddonProfileSection | null> | AddonProfileSection | null;
     /**
      * Optional save handler paired with `profileSection()` (#534).
      *
@@ -673,7 +677,7 @@ declare class AddonsManager extends BaseManager {
      * Result order follows registration order of the addons map so the
      * displayed section order is stable across renders.
      */
-    getProfileSections(user: AddonProfileUser): Promise<AddonProfileSectionEntry[]>;
+    getProfileSections(user: AddonProfileUser, ctx: ActorContext): Promise<AddonProfileSectionEntry[]>;
     /**
      * #1234: say at load when an addon still implements the pre-#1234 hook.
      *
@@ -689,7 +693,7 @@ declare class AddonsManager extends BaseManager {
      * `saveProfileSection()` handler (#534).
      *
      * Runs SEQUENTIALLY — each addon's read-modify-write of user preferences
-     * (typical implementation: `getUser → merge → updateUser`) must see the
+     * (`updateUser`'s function form, #2025) must see the
      * previous addon's writes. Parallel execution would create a same-snapshot
      * race where two addons read identical preferences, each merge their own
      * keys, and the second writer clobbers the first writer's changes.

package/lib/src/managers/AssetManager.d.ts

@@ -67,10 +67,11 @@ declare class AssetManager extends BaseManager {
     /**
      * Return all AssetRecords referenced by the given page slug.
      *
-     * O(1) index lookup + one getById() call per referenced asset.
+     * O(1) index lookup + one provider lookup per referenced asset.
      * Stale entries (asset deleted or provider removed) are silently filtered out.
+     * Nothing for a caller who may not read assets (`asset-read`, #2018).
      */
-    getAssetsForPage(slug: string): Promise<AssetRecord[]>;
+    getAssetsForPage(ctx: ActorContext, slug: string): Promise<AssetRecord[]>;
     /**
      * Remove a page's entry from the reverse index.
      * Call this when a page is deleted or renamed.
@@ -103,8 +104,11 @@ declare class AssetManager extends BaseManager {
     /**
      * Retrieve a single asset by id.  If providerId is given only that provider
      * is checked; otherwise all providers are tried in registration order.
+     * Null for a caller who may not read assets (`asset-read`, asked of the PDP
+     * with `ctx`, as FileManager asks for the public place; #2018).
      */
-    getById(id: string, providerId?: string): Promise<AssetRecord | null>;
+    getById(ctx: ActorContext, id: string, providerId?: string): Promise<AssetRecord | null>;
+    private lookup;
     /**
      * Generate or retrieve a cached thumbnail.
      * Requires the provider to declare the 'thumbnail' capability.

package/lib/src/managers/ExportManager.js

@@ -539,6 +539,11 @@ class ExportManager extends BaseManager {
      * @returns {Promise<void>}
      */
     async deleteExport(filename) {
+        // Only a plain file name inside the export folder: never a path that
+        // reaches another folder.
+        if (!filename || filename !== path.basename(filename) || filename === '.' || filename === '..') {
+            throw new Error(`Not an export file name: ${filename}`);
+        }
         const filePath = path.join(this.exportDirectory, filename);
         await fs.unlink(filePath);
         logger.info(`Deleted export: ${filename}`);

package/lib/src/managers/ImportManager.d.ts

@@ -31,8 +31,8 @@ import BaseManager, { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { IContentConverter } from '../converters/IContentConverter.js';
 import { type ZipReadLimits } from '../utils/zipArchive.js';
-import { type JobContext } from '../context/JobContext.js';
-import type { IceLedger, IceReceiver, IceRunReport, IceRunRequest, IceShim, RegisteredShim } from '../ice/types.js';
+import type { JobContext } from '../context/JobContext.js';
+import type { IceLedger, IceOriginalChoices, IceReceiver, IceRunReport, IceRunRequest, IceShim, RegisteredShim } from '../ice/types.js';
 /**
  * Options for import operations
  */
@@ -253,6 +253,12 @@ export type TakeoutImportReport = {
      */
     reportPage?: string;
 };
+/** A receiver the import screen may offer this user (#2021): its id, label and original-file choices (D11). */
+export interface UsableReceiver {
+    id: string;
+    label?: string;
+    originals: Required<IceOriginalChoices>;
+}
 /**
  * Import Manager class
  *
@@ -310,11 +316,24 @@ declare class ImportManager extends BaseManager {
     listShims(): Array<Pick<RegisteredShim, 'id' | 'owner' | 'label' | 'direction' | 'produces' | 'receivers'> & {
         enabled: boolean;
     }>;
-    /** The receivers this context may use (D5): each answers with its own existing permission. */
-    receiversFor(ctx: ActorContext): Promise<Array<{
-        id: string;
-        label?: string;
-    }>>;
+    /**
+     * The receivers this context may use (D5): each answers with its own
+     * existing permission. Each comes with the original-file choices it offers
+     * (D11), for the import screen (#2021).
+     */
+    receiversFor(ctx: ActorContext): Promise<UsableReceiver[]>;
+    /**
+     * The original-file choices a receiver offers (D11, #2021): what it
+     * declares, else all three; its default when it names one it allows, else
+     * `ngdpbase.import.engine.default-original` when allowed, else the first.
+     */
+    private originalChoices;
+    /**
+     * The request as the engine runs it: the receiver's default original when
+     * none was chosen, and a refusal for a choice the receiver does not offer
+     * (D11, #2021). An unknown receiver is left for the run to report.
+     */
+    private withOriginal;
     /**
      * Run one import now and wait for it. For code already off the request
      * path: an add-on's own background job, a test. A route uses
@@ -332,6 +351,8 @@ declare class ImportManager extends BaseManager {
     enqueueImport(request: IceRunRequest, ctx: JobContext): Promise<string>;
     /** A run's report, to the person it runs as; null to anyone else. */
     getImportRun(runId: string, ctx: ActorContext): IceRunReport | null;
+    /** The runs this process holds for the user `ctx` names, newest first (#2021): their own, never anyone else's. */
+    importRunsFor(ctx: ActorContext): IceRunReport[];
     /** Use this ledger instead of the file one: a test's, or a database table's. */
     setImportLedger(ledger: IceLedger): void;
     private newRunReport;

package/lib/src/managers/OrganizationManager.d.ts

@@ -88,13 +88,15 @@ declare class OrganizationManager extends BaseManager {
      * problem actually bites.
      */
     getInstallOrg(): Promise<Organization | null>;
-    getById(id: string): Promise<Organization | null>;
-    getByFile(filename: string): Promise<Organization | null>;
+    /** One organization by `@id`, for a caller who may read contacts (`contact-read`), or core's own work (#2018). */
+    getById(ctx: ActorContext, id: string): Promise<Organization | null>;
+    /** One organization by its file name, decided as {@link getById} (#2018). */
+    getByFile(ctx: ActorContext, filename: string): Promise<Organization | null>;
     /** #1006: how many organizations this instance holds. Count only. */
     getManagerStats(): Promise<ManagerStats>;
     /** Every organization, for a caller who may read contacts (`contact-read`). */
     list(ctx: ActorContext): Promise<Organization[]>;
-    /** One organization by `@id`, for a caller who may read contacts (`contact-read`). */
+    /** One organization by `@id`: {@link getById}. */
     get(ctx: ActorContext, id: string): Promise<Organization | null>;
     /**
      * Organizations whose `name`, `legalName`, `email` or a contact point's

package/lib/src/managers/PageManager.d.ts

@@ -1128,6 +1128,38 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * const deleted = await pageManager.deletePage('Old Page', req.userContext);
      */
     deletePage(identifier: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Delete the pages a test made (#2008): every shared page carrying the
+     * `test-artifact` system keyword (#1355), and never a page without it.
+     * `only` narrows the set further — a deleted test account's profile is
+     * `{ author, systemCategory: 'user-profile' }`.
+     *
+     * Each page is recorded as `page-delete` before it is deleted (on-failure
+     * refuse: a page whose record cannot be written is not deleted), then goes
+     * through {@link deletePage}, so the delete is soft and the shared indexes
+     * follow. One page's failure never stops the rest; it is reported.
+     *
+     * The caller decides who may ask: the sweep route asks `admin-system`, and
+     * an account delete has already been decided as `user-delete`. Private
+     * vault pages are not in the shared index, so they are not reached here.
+     *
+     * @param ctx - Who is acting; named in every record
+     * @param only - Narrow to one author and/or system-category
+     */
+    deleteTestArtifacts(ctx: ActorContext, only?: {
+        author?: string;
+        systemCategory?: string;
+    }): Promise<{
+        deleted: Array<{
+            title: string;
+            uuid: string;
+        }>;
+        failed: Array<{
+            title: string;
+            uuid: string;
+            error: string;
+        }>;
+    }>;
     /**
      * The name a page was reached by, as the shared indexes key it: a private
      * page's path (#1456), else its title — the caller may have used a uuid or

package/lib/src/managers/PersonManager.d.ts

@@ -23,8 +23,13 @@ export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' |
  * `linkAccount` take the caller's context first and ask the PDP: `contact-read`
  * to list, search or get; `contact-manage` to change (`linkAccount` also `user-edit`). Each change is recorded as
  * the `contact-manage` audit event. A refusal throws `ContactRefusedError`.
- * `getById` / `getByIdentifier` stay as context-free lookups for core's own
- * hot paths (RoleManager resolves roles through them on every request).
+ *
+ * Every lookup takes the caller's context too (#2018): `getById`,
+ * `getByIdentifier` and `getByUserIdentifier`. A user reads their own identity
+ * record, and `update` changes it, under `profile-manage`; anyone else's needs
+ * `contact-read` / `contact-manage`. Core's own reads (RoleManager resolving
+ * roles on every request, UserManager's account lifecycle) pass the system
+ * context, allowed without a policy evaluation (`requireRecordAccess`).
  *
  * A later sign-up joins a person with no account in one of two ways: the new
  * account confirms an emailed link (`offerSignUpLink` → `confirmSignUpLink`),
@@ -32,8 +37,8 @@ export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' |
  * person keeps its `@id` and takes the account; the person made for the new
  * account is folded into it and removed, so there is never a second person.
  *
- * `getByUserIdentifier(username)` remains as a lazy-migration entry point
- * for legacy users that pre-date the sync wiring.
+ * `getByUserIdentifier(ctx, username)` remains as a lazy-migration entry
+ * point for legacy users that pre-date the sync wiring.
  */
 declare class PersonManager extends BaseManager {
     readonly description = "Canonical Person records (#617)";
@@ -56,15 +61,26 @@ declare class PersonManager extends BaseManager {
      */
     backupFolders(): BackupFolder[];
     getProvider(): PersonProvider | null;
-    getById(id: string): Promise<Person | null>;
-    getByIdentifier(identifier: string): Promise<Person | null>;
+    /**
+     * One identity record by `@id` (#2018): the caller's own under
+     * `profile-manage`, anyone else's under `contact-read`, core's own work
+     * under the system context. A refusal throws `ContactRefusedError`.
+     */
+    getById(ctx: ActorContext, id: string): Promise<Person | null>;
+    /**
+     * The identity record whose `identifier` is `identifier` (a username, or a
+     * contact's `person:<uuid>`), decided as {@link getById} before it is read.
+     */
+    getByIdentifier(ctx: ActorContext, identifier: string): Promise<Person | null>;
+    private cachedById;
+    private cachedByIdentifier;
     /** #1006: how many people this instance holds. Count only, never records. */
     getManagerStats(): Promise<ManagerStats>;
     /** True when the person has no account: its identifier is `person:<uuid>` (#1930). */
     static isAccountless(person: Pick<Person, 'identifier'>): boolean;
     /** Every person, for a caller who may read contacts (`contact-read`). */
     list(ctx: ActorContext): Promise<Person[]>;
-    /** One person by `@id`, for a caller who may read contacts (`contact-read`). */
+    /** One person by `@id`: {@link getById}, the caller's own under `profile-manage`, anyone else's under `contact-read`. */
     get(ctx: ActorContext, id: string): Promise<Person | null>;
     /**
      * Persons whose name (`name`, `givenName`, `familyName`) or `email` contains
@@ -82,7 +98,11 @@ declare class PersonManager extends BaseManager {
      * person yet: that is how UserManager makes the person for a new account.
      */
     create(ctx: ActorContext, input: PersonInput): Promise<Person>;
-    /** Change a person's fields, affiliations included. `@id` and `identifier` never change here. */
+    /**
+     * Change a person's fields, affiliations included. `@id` and `identifier`
+     * never change here. The caller's own identity record under
+     * `profile-manage`, anyone else's under `contact-manage` (#2018).
+     */
     update(ctx: ActorContext, id: string, patch: PersonUpdate): Promise<Person | null>;
     delete(ctx: ActorContext, id: string): Promise<boolean>;
     /**
@@ -123,7 +143,10 @@ declare class PersonManager extends BaseManager {
      * to it, and that person is removed. Never a second person.
      */
     private join;
-    /** Each affiliation names an organization that exists; `role` is trimmed text. Throws on any other shape. */
+    /**
+     * Each affiliation names an organization that exists, looked up with the
+     * caller's context; `role` is trimmed text. Throws on any other shape.
+     */
     private checkedAffiliations;
     private configNumber;
     /**
@@ -136,9 +159,11 @@ declare class PersonManager extends BaseManager {
      *
      * Returns the Person paired to `username`. If none exists and a matching
      * User does, a Person is created from the User's email/displayName and
-     * persisted. Subsequent calls return the persisted record.
+     * persisted. Subsequent calls return the persisted record. Decided as
+     * {@link getByIdentifier} (#2018): a signed-in user's own under
+     * `profile-manage` ("your receipts"), anyone else's under `contact-read`.
      */
-    getByUserIdentifier(username: string): Promise<Person | null>;
+    getByUserIdentifier(ctx: ActorContext, username: string): Promise<Person | null>;
     private requireProvider;
     private getMetrics;
     private normalizeProviderName;

package/lib/src/managers/RoleManager.d.ts

@@ -12,6 +12,9 @@ declare class RoleManager extends BaseManager {
     private storageDir;
     private memberCache;
     private byOrgPositionCache;
+    private cacheGeneration;
+    /** #2015: one membership change at a time per role record, read included. */
+    private readonly membership;
     private metricsRef;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
@@ -42,7 +45,8 @@ declare class RoleManager extends BaseManager {
     backupFolders(): BackupFolder[];
     /** Provider accessor, mainly for tests. */
     getProvider(): RoleProvider | null;
-    getById(id: string): Promise<Role | null>;
+    /** One role record by `@id`: its members are identity records, so `contact-read`, or core's own work (#2018). */
+    getById(ctx: ActorContext, id: string): Promise<Role | null>;
     getByOrgAndPosition(organizationId: string, namedPosition: string): Promise<Role | null>;
     listByMember(personId: string): Promise<Role[]>;
     list(): Promise<Role[]>;
@@ -65,8 +69,13 @@ declare class RoleManager extends BaseManager {
      *
      * Returns `[]` when PersonManager is unavailable, the user has no Person
      * record, no record lists them, or the lookup throws.
+     *
+     * `ctx` is who is asking (#2018), decided by PersonManager's door: a user
+     * about themselves under `profile-manage`, about anyone else under
+     * `contact-read`; core's own work passes the system context. A refusal is
+     * thrown as `ContactRefusedError`, never answered as "no roles".
      */
-    resolveUserRoles(username: string): Promise<string[]>;
+    resolveUserRoles(ctx: ActorContext, username: string): Promise<string[]>;
     /**
      * The `required-aal` levels the OPERATOR set in their own config (#448,
      * #1523), as opposed to the shipped defaults. An operator's level that no
@@ -86,15 +95,26 @@ declare class RoleManager extends BaseManager {
      * `anonymous`) requires nothing beyond being signed in.
      */
     roleRequiredAal(): Record<string, 1 | 2 | 3>;
-    hasRole(username: string, roleName: string): Promise<boolean>;
-    /** Assign one role to an existing account, and record it (#1204). */
+    /** Whether `username` holds `roleName` now, asked by `ctx`; decided as {@link resolveUserRoles} (#2018). */
+    hasRole(ctx: ActorContext, username: string, roleName: string): Promise<boolean>;
+    /**
+     * Assign one role to an existing account, and record it (#1204). A role
+     * that cannot be given is refused (#2015): the error is thrown, admins are
+     * notified, and the attempt is recorded as a failed user-edit.
+     */
     assignRole(username: string, roleName: string, ctx: ActorContext): Promise<boolean>;
-    /** Remove one role from an existing account, and record it (#1204). */
+    /** Remove one role from an existing account, and record it (#1204); refused like `assignRole` when it cannot be done. */
     removeRole(username: string, roleName: string, ctx: ActorContext): Promise<boolean>;
     /**
      * Make the user's memberships go from `oldRoles` to `newRoles`. Used by
      * UserManager when an account is created or edited; the account write
      * records its own audit event, so this records none.
+     *
+     * All or nothing (#2015): when any change cannot be made, the ones already
+     * made are undone and a `RoleChangeError` is thrown, after it is logged as
+     * an error and admins are notified. That includes a change that cannot even
+     * be attempted: no PersonManager, no Person record for the username, or no
+     * anchor Organization.
      */
     applyRoleDiff(username: string, oldRoles: string[], newRoles: string[]): Promise<void>;
     /**
@@ -108,28 +128,67 @@ declare class RoleManager extends BaseManager {
      * a role change and is recorded as one, under the system context `ctx`,
      * deferred until the audit sink is up when this runs at boot.
      *
+     * #2015: each account gets the role or not. One that does not is recorded as
+     * a failed user-edit, and every miss is an error in the log and one error
+     * notification for admins naming the accounts to fix by hand. The boot goes
+     * on: nobody asked, so there is nobody to refuse.
+     *
      * @returns how many accounts were given the role (0 once it has been given)
      */
     grantToEveryAccountOnce(roleName: string, usernames: readonly string[], ctx: JobContext): Promise<number>;
     /**
      * Move every membership held by one Person `@id` to another (#1930): when
      * PersonManager joins an account to an existing person, the roles the
-     * account's person held go with the account. One write per role record;
-     * returns how many records changed. PersonManager's join records the change.
+     * account's person held go with the account. Returns how many records
+     * changed. PersonManager's join records the change. All or nothing (#2015).
      */
     moveMemberships(fromPersonId: string, toPersonId: string): Promise<number>;
-    /** Remove a deleted account's Person from every role it held. */
-    removeAllMemberships(username: string): Promise<void>;
     /**
-     * Add the user's Person `@id` to the role record for (installOrg, roleName).
-     * Idempotent: a no-op when the Person is already a member.
-     *
-     * Failures are logged, not thrown — account writes must succeed even when
-     * role storage is degraded. #1027: every abandon path says why, because a
-     * silent one is indistinguishable from success.
+     * Remove a deleted account's Person from every role it held. All or nothing
+     * (#2015): when any removal fails the others are put back and it throws, so
+     * the account delete is refused. Returns the undo, for a delete that fails
+     * after this: it gives every role back. An account with no Person holds no
+     * role, so there is nothing to remove.
+     */
+    removeAllMemberships(username: string): Promise<() => Promise<void>>;
+    /** The roles `username` gains and loses, all or nothing; `notify` false lets a batch send one notice. */
+    private changeRoles;
+    /**
+     * The Person `@id` and anchor Organization a username's role changes need
+     * (#1027). Either missing refuses the change (#2015): an account must not
+     * be left without the role it was given, nor keep one it was meant to lose.
+     */
+    private membershipTarget;
+    /** One member change and its inverse. */
+    private memberChange;
+    /**
+     * Make each change in turn (#2015). When one fails, undo the ones made, in
+     * reverse, and throw. Returns the changes made, for a later undo.
+     */
+    private allOrNothing;
+    /** Undo `done`, newest first; returns the labels that could not be undone. */
+    private undoAll;
+    /**
+     * A role change that did not happen is always an error (operator,
+     * 2026-10-23): logged at error level, and an error notification for admins
+     * unless the caller sends one for a whole batch. Returns the error to throw.
+     */
+    private roleFailure;
+    /** An error notification for admins; a notification that cannot be sent is logged, never thrown. */
+    private reportToAdmins;
+    /** #2015: the membership queue's key for one role record. */
+    private membershipKey;
+    /**
+     * Make `personId` a member of the role record, or not, one change at a time
+     * per record (#2015). The record is read inside the queue, so a change never
+     * works from a member list another change has since replaced. A missing
+     * record is created in `createIn` for an add; with no `createIn` an add to a
+     * missing record throws, and a removal from one changes nothing. False,
+     * writing nothing, when the person already is (or is not) a member.
      */
-    private addMember;
-    private removeMember;
+    private setMember;
+    /** assignRole / removeRole: the change, recorded as a user-edit whether it happened or not (#1204, #2015). */
+    private recordedRoleChange;
     /**
      * The role record for (installOrg, namedPosition), created when missing.
      *

package/lib/src/managers/UserManager.d.ts

@@ -153,7 +153,7 @@ interface UserCreateInput {
 /**
  * User update input data
  */
-interface UserUpdateInput {
+export interface UserUpdateInput {
     email?: string;
     displayName?: string;
     password?: string;
@@ -166,6 +166,16 @@ interface UserUpdateInput {
     profilePage?: string;
     [key: string]: unknown;
 }
+/**
+ * A change worked out from the account as it is now (#2025), the function form
+ * of `updateUser`. It runs inside the account's key, is handed a copy of the
+ * account without the password hash (an add-on's own fields included, as
+ * `UserUpdateInput` allows them), and returns the fields to merge, or
+ * `undefined` to change nothing.
+ */
+export type UserUpdateFn = (current: Omit<User, 'password'> & {
+    [key: string]: unknown;
+}) => UserUpdateInput | undefined | Promise<UserUpdateInput | undefined>;
 /**
  * UserManager - Handles user authentication, authorization, and roles
  *
@@ -208,6 +218,8 @@ declare class UserManager extends BaseManager {
     private provider;
     private providerClass?;
     private passwordSalt?;
+    /** One read-merge-write at a time per account, keyed by the normalized username (#2025). */
+    private readonly accountWrites;
     /**
      * Creates a new UserManager instance
      *
@@ -358,6 +370,15 @@ declare class UserManager extends BaseManager {
     upgradePasswordHash(username: string, newHash: string, legacy: boolean): Promise<void>;
     /** Count a completed sign-in on the account: last sign-in and sign-in count (#1758; AuthManager calls it for a sign-in, never a re-check). */
     recordSignIn(username: string): Promise<void>;
+    /** Run `task` inside the account's key: one read-merge-write at a time per account (#2025). Not re-entrant. */
+    private inAccountKey;
+    /**
+     * Read an account, change it and write it back, inside its key (#2025): for
+     * core's own bookkeeping (sign-in counters, the hash upgrade, the profile
+     * page), which is not an edit and is not recorded. False when there is no
+     * such account.
+     */
+    private patchAccount;
     /**
      * Check if a display name conflicts with existing page names or other users
      * @param {string} displayName - Display name to check
@@ -400,6 +421,12 @@ declare class UserManager extends BaseManager {
      * @returns {Promise<Omit<User, 'password'>>} Created user (without password)
      */
     createUser(userData: UserCreateInput, ctx: ActorContext): Promise<Omit<User, 'password'>>;
+    /**
+     * Take back an account whose roles could not be given (#2015): its Person,
+     * then the account. A failure here is an error in the log; the role failure
+     * that caused it is what the caller is told.
+     */
+    private undoAccountCreate;
     /**
      * Update user
      */
@@ -419,7 +446,31 @@ declare class UserManager extends BaseManager {
      * which accounts exist.
      */
     resetPasswordWithRecoveryWords(username: string, words: string, newPassword: string, ctx: ActorContext): Promise<boolean>;
-    updateUser(username: string, updates: UserUpdateInput, ctx: ActorContext): Promise<User>;
+    /**
+     * Change an account (#2025: one change at a time per account).
+     *
+     * `updates` is the fields to merge, or a function that works them out from
+     * the account as it is now: `(current) => updates`. The function runs inside
+     * the account's `KeyedSerial` key, between the read and the write, so two
+     * changes to one account never read the same old record. It gets a copy of
+     * the account without the password hash, and returns the fields to merge, or
+     * `undefined` to change nothing (nothing is written or recorded). It must not
+     * call `updateUser` for the same account: the key is not re-entrant.
+     * Either form is checked, applied and recorded the same way.
+     *
+     * Returns the account as written (as read, when nothing changed), without
+     * the password hash: the hash never leaves UserManager except to the
+     * password check (`storedPasswordHash`).
+     */
+    updateUser(username: string, updates: UserUpdateInput | UserUpdateFn, ctx: ActorContext): Promise<Omit<User, 'password'>>;
+    /**
+     * The steps of an account change that come after the write, outside the
+     * account's key: they reach other managers, which may change the account
+     * themselves.
+     */
+    private finishEdit;
+    /** Read, check and write one account change. Runs inside the account's key (#2025). */
+    private editAccount;
     /**
      * Delete user
      */
@@ -469,6 +520,8 @@ declare class UserManager extends BaseManager {
      * who changed it, so the record says why.
      */
     private personSyncContext;
+    /** Core's bookkeeping for an account write, the read of its roles included (#2018): the system context, saying what and who changed the account. */
+    private lifecycleContext;
     /**
      * Persist a Person record paired with a newly-created User. The install's
      * anchor org (when configured) is referenced via `memberOf`; without it

package/lib/src/security/PolicyDecisionPoint.d.ts

@@ -27,8 +27,15 @@ import type { PermissionSubject, JobSubject } from '../managers/UserManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { Decision, DecisionRequest, Policy } from '../types/Policy.js';
 import { type RoleGrant } from '../utils/roleGrants.js';
+import { type ActorContext } from '../context/ActorContext.js';
 export declare const POLICIES_KEY = "ngdpbase.access.policies";
 export declare const POLICIES_ENABLED_KEY = "ngdpbase.access.policies.enabled";
+/**
+ * What `decide`, `permits` and `holds` take (#2022): the caller's own context
+ * — a request's `PermissionSubject` or a job's `JobContext` — or a subject
+ * already in decision form (`JobSubject`). A caller passes what it was given.
+ */
+type DecisionInput = ActorContext | JobSubject | null | undefined;
 export declare class PolicyDecisionPoint extends BaseManager {
     /**
      * A manager so every PEP can reach it through `engine.getManager`, the same
@@ -84,10 +91,11 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * of {@link decide} for a capability. It was `UserManager.hasPermission`
      * until #1431 step 14; the decision was already here, only the door moved.
      *
-     * Takes a `PermissionSubject` — the request's own identity, forwarded from
-     * `req.userContext` (WikiContext, ApiContext, ParseContext) or a
-     * `JobContext` for work with no request (#631). Roles arrive already
-     * resolved; the session middleware did that once per request.
+     * Takes the caller's context as it was given (#2022): a `PermissionSubject`
+     * — the request's own identity, forwarded from `req.userContext`
+     * (WikiContext, ApiContext, ParseContext), roles already resolved by the
+     * session middleware — or a `JobContext` for work with no request (#631),
+     * which the PDP turns into a subject itself. Never convert one first.
      *
      * #1173 Part B: the username-string overload this method once accepted is
      * gone. A string cannot carry `viaToken`, so the agent-token ceiling below
@@ -98,12 +106,13 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * separate question {@link userHoldsPermission} — "does the named user hold
      * this?" — which is a lookup about somebody else, not an authorisation.
      *
-     * @param subject - The identity being authorised, with `roles` resolved and
-     *                  `viaToken` present when a bearer token authenticated it.
+     * @param subject - The caller's context: the request's subject, with
+     *                  `viaToken` present when a bearer token authenticated it,
+     *                  or a job's context.
      * @param action - Action/permission to check (e.g., 'page-create', 'user-read')
      * @returns True if the subject may perform the action under current policy
      */
-    permits(subject: PermissionSubject | JobSubject | null | undefined, action: string): Promise<boolean>;
+    permits(subject: DecisionInput, action: string): Promise<boolean>;
     /**
      * Does the subject HOLD this permission (#1635)? Policy alone — the
      * step-up freshness rule is not applied. A different question from
@@ -112,7 +121,7 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * person whose sign-in is not fresh still sees the way to the prompt that
      * makes it fresh. A door never asks this.
      */
-    holds(subject: PermissionSubject | JobSubject | null | undefined, action: string): Promise<boolean>;
+    holds(subject: DecisionInput, action: string): Promise<boolean>;
     /**
      * Step-up (#1525, #1635), decided here — in the one place every door asks —
      * rather than by routes in front of the doors. A permission marked
@@ -252,7 +261,7 @@ export declare class PolicyDecisionPoint extends BaseManager {
      *    time, not at enqueue time (#631, #1212).
      * 4. __The policies__, through `PolicyEvaluator`.
      */
-    decide(subject: PermissionSubject | JobSubject | null | undefined, request: DecisionRequest): Promise<Decision>;
+    decide(subject: DecisionInput, request: DecisionRequest): Promise<Decision>;
     /** `decide`, with the step-up rule applied or not — {@link holds} is the only caller that leaves it out. */
     private evaluate;
 }

package/lib/src/security/PolicyInformationPoint.d.ts

@@ -1,5 +1,5 @@
 import BaseManager from '../managers/BaseManager.js';
-import type { ActorContext } from '../context/ActorContext.js';
+import { type ActorContext } from '../context/ActorContext.js';
 import { WikiEngine } from '../types/WikiEngine.js';
 import type { AgentTokenGrant, ProxyClaim } from '../managers/UserManager.js';
 import type { Request } from 'express';
@@ -46,6 +46,12 @@ interface UserContext {
     viaProxy?: ProxyClaim;
     [key: string]: unknown;
 }
+/**
+ * What the page questions take (#2022): the caller's context as given — a
+ * request's subject or a job's `JobContext` — or a subject already in decision
+ * form. They convert it themselves, through {@link asSubject}.
+ */
+type PageQuestionCaller = ActorContext | UserContext | null | undefined;
 /**
  * Access decision log entry
  */
@@ -173,6 +179,15 @@ declare class PolicyInformationPoint extends BaseManager {
      * visitor holds, which is the safe answer for someone who no longer exists.
      */
     resolveSubjectNow(username: string | undefined): Promise<UserContext>;
+    /**
+     * The subject as a page's own rules match it (#2022): for a job's subject
+     * (`resolveRolesNow`, #1212), its username with the roles its account
+     * holds NOW, read through {@link resolveSubjectNow} — the path the PDP
+     * takes for the same subject; anyone else as carried. A job carries no
+     * roles, so matching it without this matched none, and an audience naming
+     * a role its user holds left the job out.
+     */
+    private matchableNow;
     /**
      * Who is making this request: the subject the session middleware resolved,
      * else the session's account resolved now, else the anonymous visitor.
@@ -348,14 +363,14 @@ declare class PolicyInformationPoint extends BaseManager {
      * private page gets at Tier 0: the owner, or a delegate of the owner; never
      * a role. A refusal is recorded like any page refusal (`authorization-deny`).
      *
-     * @param userContext - the request's subject, as given (null = anonymous)
+     * @param caller - the caller's context, as given: a request's subject or a job's (#2022); null is anonymous
      * @param owner - the container's owner (a private file's `creator`)
      * @param resource - what is being reached, for the record (e.g. `attachment:<id>`)
      * @param action - the action asked for (e.g. `view`)
      * @param vault - the vault inside the container, when the question is about one:
      *   a share link the owner issued gets in only for a vault it names (#1388)
      */
-    canAccessPrivateContainer(userContext: UserContext | null | undefined, owner: string, resource: string, action: string, vault?: string): boolean;
+    canAccessPrivateContainer(caller: PageQuestionCaller, owner: string, resource: string, action: string, vault?: string): boolean;
     /**
      * Check whether a user can access a given page — for cross-page checks where
      * the current WikiContext describes a DIFFERENT page than the one being
@@ -381,14 +396,14 @@ declare class PolicyInformationPoint extends BaseManager {
      *     case.
      *   - any tier returns deny.
      *
-     * @param userContext - The user requesting access (may be null / anonymous).
+     * @param caller      - The caller's context, as given: a request's subject or a job's (#2022); null / undefined is anonymous.
      * @param pageName    - Target page to check.
      * @param action      - Action verb (e.g., `'view'`, `'edit'`, `'delete'`).
      * @param knownMetadata - The page's metadata when the caller has just
      *   resolved it: the page door (#1622), which reads the page by the same
      *   resolution it decides on. Omitted, it is loaded here.
      */
-    canUserAccessPage(userContext: UserContext | null | undefined, pageName: string, action: string, knownMetadata?: PageFrontmatter): Promise<boolean>;
+    canUserAccessPage(caller: PageQuestionCaller, pageName: string, action: string, knownMetadata?: PageFrontmatter): Promise<boolean>;
     /**
      * {@link canUserAccessPage} as an affordance (#1668): would the door allow
      * this action on that page — asked only to decide whether to show a control
@@ -399,7 +414,7 @@ declare class PolicyInformationPoint extends BaseManager {
      * @param knownMetadata - As for {@link canUserAccessPage}: the page's
      *   metadata when the caller has just resolved it (`PageManager.mayShowPage`).
      */
-    pageAffordanceFor(userContext: UserContext | null | undefined, pageName: string, action: string, knownMetadata?: PageFrontmatter): Promise<boolean>;
+    pageAffordanceFor(caller: PageQuestionCaller, pageName: string, action: string, knownMetadata?: PageFrontmatter): Promise<boolean>;
     /** The cross-page check, for the door (`record`) or an affordance (#1668). */
     private crossPageDecision;
     /**
@@ -425,7 +440,7 @@ declare class PolicyInformationPoint extends BaseManager {
      * A candidate without metadata is not listed (#714's convention). Order is
      * preserved. Returns titles.
      */
-    filterAccessiblePages(userContext: UserContext | null | undefined, action: string, candidates: ReadonlyArray<{
+    filterAccessiblePages(caller: PageQuestionCaller, action: string, candidates: ReadonlyArray<{
         title: string;
         metadata: PageFrontmatter | null | undefined;
     }>): Promise<string[]>;
@@ -445,7 +460,7 @@ declare class PolicyInformationPoint extends BaseManager {
      * A refusal is audited as `authorization-deny` on the media resource, with
      * the share attribution when there is one.
      */
-    canUserAccessMediaItem(userContext: UserContext | null | undefined, item: MediaItem): Promise<boolean>;
+    canUserAccessMediaItem(caller: PageQuestionCaller, item: MediaItem): Promise<boolean>;
     /**
      * Check front matter audience / access fields (Tier 1).
      * Returns a decision object; decided=false means no front matter restriction — fall through.
@@ -462,10 +477,10 @@ declare class PolicyInformationPoint extends BaseManager {
      * write door, so a write cannot reach a page its writer is outside the
      * audience of — whatever route it came by. Records nothing; the door does.
      *
-     * @param userContext - the subject, as given
+     * @param caller - the caller's context, as given (a job's included, #2022)
      * @param metadata - the page's current frontmatter
      */
-    audienceAdmits(userContext: UserContext | null | undefined, metadata: PageFrontmatter | null | undefined): Promise<boolean>;
+    audienceAdmits(caller: PageQuestionCaller, metadata: PageFrontmatter | null | undefined): Promise<boolean>;
     /**
      * Record/audit an access decision.
      * Accepts either a single object or positional args for backward compatibility.

package/lib/src/types/User.d.ts

@@ -73,7 +73,7 @@ export interface User {
     /**
      * @deprecated since #617 iteration 3b. Role membership is now stored
      * canonically as OrganizationRole records owned by `RoleManager`; resolve
-     * a user's roles via `RoleManager.resolveUserRoles(username)`. The field
+     * a user's roles via `RoleManager.resolveUserRoles(ctx, username)`. The field
      * is retained as optional for backwards compatibility while in-flight
      * `users.json` files still carry it; the `strip-user-roles.ts` migration
      * removes it. New code MUST NOT read or write this field directly.

package/lib/src/utils/auditEventNames.generated.d.ts

@@ -50,9 +50,9 @@ export declare const AUDIT_EVENT: {
     readonly CONFIG_CHANGE: "config-change";
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     readonly CONFIG_RESET: "config-reset";
-    /** A person accepted a document they are asked to accept (#1603): which document (core's terms-of-service or privacy-policy, or an add-on's), its version and effective date, and how (sign-up, sign-in, turning an add-on on). Recorded before the acceptance is stored, which cannot proceed without it: consent must be provable */
+    /** A user accepted a document they are asked to accept (#1603): which document (core's terms-of-service or privacy-policy, or an add-on's), its version and effective date, and how (sign-up, sign-in, turning an add-on on). Recorded before the acceptance is stored, which cannot proceed without it: consent must be provable */
     readonly CONSENT_GRANT: "consent-grant";
-    /** A person's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
+    /** A user's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
     readonly CONSENT_WITHDRAW: "consent-withdraw";
     /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
     readonly CONTACT_MANAGE: "contact-manage";
@@ -112,21 +112,21 @@ export declare const AUDIT_EVENT: {
     readonly POLICY_EVALUATE: "policy-evaluate";
     /** Security posture at startup, compared against the previous start */
     readonly POSTURE_RECORDED: "posture-recorded";
-    /** Proxy grant made: someone may act for the person named in user; actor is who made it (#1762) */
+    /** Proxy grant made: someone may act for the user named in user; actor is who made it (#1762) */
     readonly PROXY_GRANT: "proxy-grant";
-    /** Proxy grant ended: revoked, or the account closed; user is the person represented, actor who ended it (#1762) */
+    /** Proxy grant ended: revoked, or the account closed; user is the user represented, actor who ended it (#1762) */
     readonly PROXY_REVOKE: "proxy-revoke";
-    /** A signed-in session started or stopped acting for someone under a proxy grant, or opens their private store: chosen, switched-back, ended because the grant no longer allows it (grant-ended, proxy-access-off), or vault-opened; user is the person represented, actor the person signed in (#1762) */
+    /** A signed-in session started or stopped acting for someone under a proxy grant, or opens their private store: chosen, switched-back, ended because the grant no longer allows it (grant-ended, proxy-access-off), or vault-opened; user is the user represented, actor the user signed in (#1762) */
     readonly PROXY_SWITCH: "proxy-switch";
-    /** Step-up: a re-authentication failed (wrong password, another person's passkey, throttled) */
+    /** Step-up: a re-authentication failed (wrong password, another user's passkey, throttled) */
     readonly REAUTH_FAILURE: "reauth-failure";
     /** Step-up: an action asked for a fresh sign-in (#1525) — or refused a delegated credential that cannot give one */
     readonly REAUTH_PROMPT: "reauth-prompt";
-    /** Step-up: the person re-authenticated, with the factor used */
+    /** Step-up: the user re-authenticated, with the factor used */
     readonly REAUTH_SUCCESS: "reauth-success";
     /** Page search; not recorded, read volume */
     readonly SEARCH_PAGE: "search-page";
-    /** People searched for; enumerating people is disclosive in a way searching pages is not. Off by default as read volume */
+    /** Users searched for; enumerating users is disclosive in a way searching pages is not. Off by default as read volume */
     readonly SEARCH_USER: "search-user";
     /** A masked configuration value shown to an administrator; the key is recorded, never the value */
     readonly SECRET_REVEAL: "secret-reveal";
@@ -146,9 +146,9 @@ export declare const AUDIT_EVENT: {
     readonly SHARE_REVOKE: "share-revoke";
     /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
     readonly SIGNINAPPROVAL_ABANDON: "signinapproval-abandon";
-    /** Sign-in approval: the person pressed Approve (#1532) */
+    /** Sign-in approval: the user pressed Approve (#1532) */
     readonly SIGNINAPPROVAL_APPROVE: "signinapproval-approve";
-    /** Sign-in approval: the person pressed Deny; that sign-in will not complete (#1532) */
+    /** Sign-in approval: the user pressed Deny; that sign-in will not complete (#1532) */
     readonly SIGNINAPPROVAL_DENY: "signinapproval-deny";
     /** Sign-in approval: a waiting sign-in expired before it was completed (#1532) */
     readonly SIGNINAPPROVAL_EXPIRE: "signinapproval-expire";

package/lib/src/utils/auditEventNames.generated.js

@@ -57,9 +57,9 @@ export const AUDIT_EVENT = {
     CONFIG_CHANGE: 'config-change',
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     CONFIG_RESET: 'config-reset',
-    /** A person accepted a document they are asked to accept (#1603): which document (core's terms-of-service or privacy-policy, or an add-on's), its version and effective date, and how (sign-up, sign-in, turning an add-on on). Recorded before the acceptance is stored, which cannot proceed without it: consent must be provable */
+    /** A user accepted a document they are asked to accept (#1603): which document (core's terms-of-service or privacy-policy, or an add-on's), its version and effective date, and how (sign-up, sign-in, turning an add-on on). Recorded before the acceptance is stored, which cannot proceed without it: consent must be provable */
     CONSENT_GRANT: 'consent-grant',
-    /** A person's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
+    /** A user's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
     CONSENT_WITHDRAW: 'consent-withdraw',
     /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
     CONTACT_MANAGE: 'contact-manage',
@@ -119,21 +119,21 @@ export const AUDIT_EVENT = {
     POLICY_EVALUATE: 'policy-evaluate',
     /** Security posture at startup, compared against the previous start */
     POSTURE_RECORDED: 'posture-recorded',
-    /** Proxy grant made: someone may act for the person named in user; actor is who made it (#1762) */
+    /** Proxy grant made: someone may act for the user named in user; actor is who made it (#1762) */
     PROXY_GRANT: 'proxy-grant',
-    /** Proxy grant ended: revoked, or the account closed; user is the person represented, actor who ended it (#1762) */
+    /** Proxy grant ended: revoked, or the account closed; user is the user represented, actor who ended it (#1762) */
     PROXY_REVOKE: 'proxy-revoke',
-    /** A signed-in session started or stopped acting for someone under a proxy grant, or opens their private store: chosen, switched-back, ended because the grant no longer allows it (grant-ended, proxy-access-off), or vault-opened; user is the person represented, actor the person signed in (#1762) */
+    /** A signed-in session started or stopped acting for someone under a proxy grant, or opens their private store: chosen, switched-back, ended because the grant no longer allows it (grant-ended, proxy-access-off), or vault-opened; user is the user represented, actor the user signed in (#1762) */
     PROXY_SWITCH: 'proxy-switch',
-    /** Step-up: a re-authentication failed (wrong password, another person's passkey, throttled) */
+    /** Step-up: a re-authentication failed (wrong password, another user's passkey, throttled) */
     REAUTH_FAILURE: 'reauth-failure',
     /** Step-up: an action asked for a fresh sign-in (#1525) — or refused a delegated credential that cannot give one */
     REAUTH_PROMPT: 'reauth-prompt',
-    /** Step-up: the person re-authenticated, with the factor used */
+    /** Step-up: the user re-authenticated, with the factor used */
     REAUTH_SUCCESS: 'reauth-success',
     /** Page search; not recorded, read volume */
     SEARCH_PAGE: 'search-page',
-    /** People searched for; enumerating people is disclosive in a way searching pages is not. Off by default as read volume */
+    /** Users searched for; enumerating users is disclosive in a way searching pages is not. Off by default as read volume */
     SEARCH_USER: 'search-user',
     /** A masked configuration value shown to an administrator; the key is recorded, never the value */
     SECRET_REVEAL: 'secret-reveal',
@@ -153,9 +153,9 @@ export const AUDIT_EVENT = {
     SHARE_REVOKE: 'share-revoke',
     /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
     SIGNINAPPROVAL_ABANDON: 'signinapproval-abandon',
-    /** Sign-in approval: the person pressed Approve (#1532) */
+    /** Sign-in approval: the user pressed Approve (#1532) */
     SIGNINAPPROVAL_APPROVE: 'signinapproval-approve',
-    /** Sign-in approval: the person pressed Deny; that sign-in will not complete (#1532) */
+    /** Sign-in approval: the user pressed Deny; that sign-in will not complete (#1532) */
     SIGNINAPPROVAL_DENY: 'signinapproval-deny',
     /** Sign-in approval: a waiting sign-in expired before it was completed (#1532) */
     SIGNINAPPROVAL_EXPIRE: 'signinapproval-expire',

package/lib/src/utils/contactAccess.d.ts

@@ -12,6 +12,12 @@
  * A route turns it into the answer with `ApiContext.enforceDeny(err.permission,
  * err.decision)`, the one place a refusal is shaped (#1431); the door never
  * builds an HTTP answer itself.
+ *
+ * Every lookup takes a context too (#2018, operator 2026-10-23), through
+ * {@link requireRecordAccess}: a user's own identity record under
+ * `profile-manage`, anyone else's under `contact-read` / `contact-manage`, and
+ * core's own reads under the system context without a policy evaluation, so
+ * resolving roles on every request stays cheap.
  */
 import { type ActorContext } from '../context/ActorContext.js';
 import type { CorePermission } from '../security/permissions.generated.js';
@@ -37,6 +43,30 @@ export declare class ContactRefusedError extends Error {
  * refuses: closed, never open.
  */
 export declare function requireContactPermission(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, also?: readonly CorePermission[]): Promise<void>;
+/**
+ * Core's own work (#2018): a boot or schedule context naming the system
+ * principal, with no token, share or proxy claim. Recognised by its fields
+ * alone, with no policy evaluation, because RoleManager resolves roles
+ * through these lookups on every request. A request never carries this
+ * context: the system principal's name is reserved, so no account holds it.
+ */
+export declare function isSystemWork(engine: EngineLike, ctx: ActorContext | null | undefined): boolean;
+/**
+ * A lookup or change of one record at a contacts door (#2018). Throws
+ * {@link ContactRefusedError} unless `ctx` may:
+ *
+ * - read it as core's own work ({@link isSystemWork}): allowed, not evaluated;
+ * - read or change its own identity record (the context's username is the
+ *   record's `identifier`): `profile-manage`, which every user holds;
+ * - read or change any other record: `contact-read` / `contact-manage`.
+ *
+ * `record` is the identity record (or what names it, `{ identifier }`); left
+ * out for a record that is never anyone's own (an organization, a role).
+ * "Own" is decided by comparing usernames, never by a role.
+ */
+export declare function requireRecordAccess(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, record?: {
+    identifier?: unknown;
+} | null): Promise<void>;
 /** What a contacts record says was done. Names fields, never their values. */
 export interface ContactChange {
     kind: 'person' | 'organization';

package/lib/src/utils/keyedSerial.d.ts

@@ -0,0 +1,31 @@
+/**
+ * KeyedSerial — one task at a time per key, within this process (#2015).
+ *
+ * A read-modify-write of one record (read the file, change it, write it back)
+ * is only safe while nothing else writes that record in between. Two role
+ * changes to one role used to interleave: each read the member list before the
+ * other wrote it, and the second write dropped the first one's member. Running
+ * every read-modify-write of a key through `run` makes them happen one after
+ * another, each reading what the last one wrote. Different keys still run side
+ * by side.
+ *
+ * What it does not do:
+ *
+ * - **Not across processes.** Two server processes sharing one data folder can
+ *   still race; no supported deployment runs that way.
+ * - **Not re-entrant.** A task must not `run` the same key again and wait for
+ *   it: the inner task queues behind the outer one, which never finishes.
+ *
+ * A failed task fails its own caller only; the next task on the key runs as
+ * usual. A key's entry is dropped once its queue is empty, so the map holds
+ * only keys with work in flight.
+ */
+export declare class KeyedSerial {
+    /** The settled tail of each key's queue: never rejects. */
+    private readonly tails;
+    /** Run `task` after every earlier task on `key` has settled; resolves or rejects as `task` does. */
+    run<T>(key: string, task: () => Promise<T>): Promise<T>;
+    /** Resolves once every task queued so far, on every key, has settled (shutdown). */
+    settled(): Promise<void>;
+}
+export default KeyedSerial;

package/lib/src/utils/privateStoreAccess.js

@@ -25,7 +25,6 @@
  * slice 4).
  */
 import { isJobContext } from '../context/ActorContext.js';
-import { toPermissionSubject } from '../context/JobContext.js';
 import { shareNamesVault } from '../types/Share.js';
 import { mixesProxyWithDelegation, proxyCarries } from './proxyClaim.js';
 export function mayActInPrivateContainer(ctx, owner, opts = {}) {
@@ -60,6 +59,5 @@ export function mayActInPrivateContainer(ctx, owner, opts = {}) {
 export async function permitsInVault(pdp, ctx, action, where) {
     if (!pdp || !mayActInPrivateContainer(ctx, where.owner, { vault: where.vault }))
         return false;
-    const subject = isJobContext(ctx) ? toPermissionSubject(ctx) : ctx;
-    return (await pdp.decide(subject, { action, resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } })).permit;
+    return (await pdp.decide(ctx, { action, resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } })).permit;
 }

package/lib/src/utils/roleChangeError.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A role change that did not happen (#2015).
+ *
+ * Operator, 2026-10-23: adding or removing a role completes or it does not
+ * happen, everywhere, and one that cannot be made is always an error. So a
+ * request that asks for several role changes either gets all of them or none:
+ * RoleManager undoes the ones that landed before the failure, then throws
+ * this, and the request that asked fails with it.
+ *
+ * The message is shown to whoever asked (an administrator's form). It names
+ * the account, the change that failed and, when it is something an
+ * administrator can fix, the reason (no Person record, no anchor
+ * Organization). Storage detail (paths, errno) stays in `cause`, for the log.
+ */
+export declare class RoleChangeError extends Error {
+    /** The change that could not be made, as `add <role>` / `remove <role>`. */
+    readonly failed: readonly string[];
+    /** Changes that landed, could not be undone, and so are still in effect. Empty when nothing was left changed. */
+    readonly notUndone: readonly string[];
+    constructor(subject: string, failed: readonly string[], options?: {
+        reason?: string;
+        cause?: unknown;
+        notUndone?: readonly string[];
+    });
+}

package/lib/src/utils/subjectMayDo.d.ts

@@ -12,10 +12,10 @@
  * had somewhere to go that is not a second evaluator: a role name skips
  * PolicyEvaluator, deny policies and the token ceiling; this does not.
  */
-import type { PermissionSubject } from '../managers/UserManager.js';
+import type { ActorContext } from '../context/ActorContext.js';
 import type { CorePermission } from '../security/permissions.generated.js';
 type EngineLike = {
     getManager: (name: string) => unknown;
 } | null | undefined;
-export declare function subjectMayDo(engine: EngineLike, subject: PermissionSubject | null | undefined, action: CorePermission): Promise<boolean>;
+export declare function subjectMayDo(engine: EngineLike, subject: ActorContext | null | undefined, action: CorePermission): Promise<boolean>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.27.0",
+  "version": "5.28.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",