@jwilleke/ngdpbase-types 5.27.0 → 5.29.0

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.29.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",