@jwilleke/ngdpbase-types 5.30.0 → 5.30.1

package/README.md

@@ -11,7 +11,7 @@ import type { AddonModule, AddonHost, WikiEngine } from '@jwilleke/ngdpbase-type
 import { buildAddonHost, openAddonTestDatabase, toCsv, formatters } from '@jwilleke/ngdpbase-types/testing';
 ```
 
-- The main entry is types only. Importing it at run time fails, on purpose. An add-on takes core's values from `host` (`AddonHost`: the request and audit helpers, the logger, `guardedFetch`, the egress tools, `isAtLeast`) and a manager's job from `engine.getManager` (such as `PageManager.pageUrl` or `PolicyDecisionPoint.usersHolding`); it never imports core's values ([#1813](https://github.com/jwilleke/ngdpbase/issues/1813)).
+- The main entry is types only. Importing it at run time fails, on purpose. An add-on takes core's values from `host` (`AddonHost`: the request and audit helpers, the logger, `guardedFetch`, the egress tools, `isAtLeast`, `zonedParts`) and a manager's job from `engine.getManager` (such as `PageManager.pageUrl` or `PolicyDecisionPoint.usersHolding`); it never imports core's values ([#1813](https://github.com/jwilleke/ngdpbase/issues/1813)).
 - `/testing` is for tests. `buildAddonHost(slug, defaults, setEnabledForPerson?, engine?)` is the real host; `host.setEnabledForPerson` calls the setter you pass (it refuses without one), and `engine` names the system principal `host.systemContext(reason)` uses (core's fallback without one). `openAddonTestDatabase(owner, { migrations, ledgerTable })` is the handle `openAddonDatabase` returns, in memory. `toCsv` is `ExportManager.toCsv`. `formatters` is a plugin's `context.formatters`.
 
 The add-on guide is [docs/guides/addons-developer-guide.md](https://github.com/jwilleke/ngdpbase/blob/master/docs/guides/addons-developer-guide.md).

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

@@ -23,8 +23,9 @@ export type { PermissionSubject } from '../../src/managers/UserManager.js';
 export type { Decision } from '../../src/types/Policy.js';
 export type { PluginContext, PluginParams, PluginFormatters } from '../../src/managers/PluginManager.js';
 export type { SimplePlugin } from '../../src/plugins/types.js';
+export type { KeyedSerial } from '../../src/utils/keyedSerial.js';
 export type { AuditEvent } from '../../src/utils/auditEvents.js';
-export type { JobRunContext } from '../../src/managers/BackgroundJobManager.js';
+export type { default as BackgroundJobManager, JobDefinition, JobResult, JobRunContext } from '../../src/managers/BackgroundJobManager.js';
 export type { default as DatabaseManager, AddonDatabaseOptions } from '../../src/managers/DatabaseManager.js';
 export type { Migration } from '../../src/providers/sqliteMigrations.js';
 export type { AddonDatabaseDeclaration, DatabaseEncrypt } from '../../src/utils/addonDatabaseRules.js';
@@ -36,7 +37,7 @@ 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, IceOriginalChoices, 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, OriginalKeep, 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 AuthManager, InviteOutcome, InvitationView } from '../../src/managers/AuthManager.js';

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

@@ -71,6 +71,15 @@ export interface JobContext {
     requestedAt: string;
     /** Why, for origins with no person to ask. Free text, for the audit record. */
     reason?: string;
+    /**
+     * The scheduled job this run acts as (#1999): its id. Set by
+     * BackgroundJobManager on a scheduled slot's context, never on a run
+     * started by hand. When a policy names the job (`{ "type": "job", "value":
+     * "<id>" }`), its decisions are made as `job:<id>`, holding only what such
+     * policies grant; when none does, as the system principal, as before. Only
+     * the system principal's context can act as a job.
+     */
+    job?: string;
 }
 /** The shape a request-bound context exposes; both WikiContext and ApiContext satisfy it. */
 export interface RequestIdentity {

package/lib/src/context/JobContext.js

@@ -147,7 +147,9 @@ export function toPermissionSubject(ctx) {
         resolveRolesNow: true,
         ...(ctx.viaToken ? { viaToken: ctx.viaToken } : {}),
         ...(ctx.viaShare ? { viaShare: ctx.viaShare } : {}),
-        ...(ctx.viaProxy ? { viaProxy: ctx.viaProxy } : {})
+        ...(ctx.viaProxy ? { viaProxy: ctx.viaProxy } : {}),
+        // #1999: the job a scheduled run acts as, for the PIP to resolve.
+        ...(ctx.job ? { job: ctx.job } : {})
     };
 }
 /** One line for a log or an audit record: who, from where, and how. */

package/lib/src/context/bootActions.js

@@ -64,6 +64,8 @@ export function attributedTo(ctx) {
             origin: ctx.origin,
             reason: ctx.reason ?? null,
             requestedAt: ctx.requestedAt,
+            // #1999: a scheduled run names the job it acts as on every row it records.
+            ...(ctx.job ? { job: ctx.job } : {}),
             // #2059: the delegation a request-origin job was queued under, by kind,
             // with the same precedence as a request's own record (`actorOf`).
             ...(ctx.viaToken ? { delegated: 'token' } : ctx.viaShare ? { delegated: 'share' } : proxyMeta)

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

@@ -1,5 +1,26 @@
 import { type ZipReadLimits } from '../utils/zipArchive.js';
 import type { IceUpload } from './types.js';
+/**
+ * A file's media type by its extension (#2061): how the engine labels a file
+ * it unpacks from a zip, and how the folder import labels a file it reads.
+ * A typed table, not configuration: it states what each format is, which is
+ * not a site's choice. What a site decides is which types it takes, and that
+ * is already its attachment allow-list (and a receiver's `originals.types`).
+ */
+export declare const MEDIA_TYPE_BY_EXTENSION: Readonly<Record<string, string>>;
+/** A file's media type by its extension alone: {@link MEDIA_TYPE_BY_EXTENSION}, else `application/octet-stream`. */
+export declare function mediaTypeByExtension(name: string): string;
+/**
+ * The media type of a file unpacked from a zip (#2061): its extension's,
+ * checked against its bytes where that is cheap. JSON must start with `{` or
+ * `[` (NDJSON with `{`), XML with `<`; one that does not is
+ * `application/octet-stream`. Then the upload door's own rule
+ * (`resolveUploadMime`): bytes that show a type decide (an XML file with an
+ * `<?xml` prolog is `text/xml`), and a claim they do not bear out is
+ * `application/octet-stream`. So the type a receiver is handed is the type
+ * the door stores.
+ */
+export declare function memberMediaType(name: string, bytes: Buffer): string;
 /** A file's fingerprint: SHA-256 of its bytes, hex. */
 export declare function fingerprint(bytes: Buffer): string;
 /**
@@ -15,8 +36,9 @@ export declare function isNoise(filePath: string, patterns: readonly string[]):
 export declare function isZip(upload: IceUpload): boolean;
 /**
  * Unpack the zips among the uploads into the files they hold, named
- * `archive.zip/inner/path`. A nested zip is unpacked too. Everything else is
- * passed through. Limits are per archive (`ZipReadLimits`), so a small
+ * `archive.zip/inner/path`, each with its media type ({@link memberMediaType},
+ * #2061). A nested zip is unpacked too. Everything else is passed through,
+ * with the type its request gave it. Limits are per archive (`ZipReadLimits`), so a small
  * archive that expands enormously stops at the budget. An archive that cannot
  * be read is returned in `unreadable`, with why; the rest go on.
  */

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

@@ -0,0 +1,40 @@
+/**
+ * The allowance a keep at upload carries to the upload door (#2061).
+ *
+ * A receiver that keeps originals in its own encrypted vault (phr) declares
+ * the media types it keeps (`originals.types`). The site's attachment
+ * allow-list does not name them (FHIR JSON, C-CDA XML), so the door would
+ * refuse the keep. The exemption is narrow, and lives here, not in a flag:
+ *
+ * - the engine opens one {@link OriginalKeep} for one receiver, one user and
+ *   one `keepOriginal` call, and closes it when the call returns;
+ * - the receiver passes it to `AttachmentManager.uploadAttachment` as its
+ *   `keep` option, unchanged;
+ * - the door honours it only while it is open, and only for a file going
+ *   into that user's own vault of a system-category the receiver's add-on
+ *   declares ({@link keepAllowsInto}). Anywhere else it changes nothing.
+ *
+ * An object the engine did not open is never honoured, whatever it says.
+ */
+import type { ActorContext } from '../context/ActorContext.js';
+import type { OriginalKeep, RegisteredReceiver } from './types.js';
+/** Open a keep for one call of `receiver.keepOriginal` with `ctx`. Close it with {@link closeOriginalKeep}. */
+export declare function openOriginalKeep(receiver: RegisteredReceiver, ctx: ActorContext): OriginalKeep;
+/** The call is over: the keep is honoured no more. */
+export declare function closeOriginalKeep(keep: OriginalKeep): void;
+/** Where an upload is going, as the door resolved it. */
+export interface KeepDestination {
+    /** Who is uploading: the request's username. */
+    uploader: string;
+    /** The vault's owner. */
+    owner: string;
+    /** The add-on whose system-category declares the vault (`StoreKind.owner`); null when no category does. */
+    vaultAddon: string | null;
+}
+/**
+ * Does this keep apply to this upload? Only an open keep, for a file going
+ * into its user's own vault of a system-category its receiver's add-on
+ * declares, uploaded by that user. A `false` leaves the upload exactly as
+ * any other: the site's allow-list decides.
+ */
+export declare function keepAllowsInto(keep: OriginalKeep | undefined, to: KeepDestination): boolean;

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

@@ -130,6 +130,34 @@ export interface IceOriginalChoices {
     allowed: OriginalChoice[];
     /** One of `allowed`. Default: `ngdpbase.import.engine.default-original` when allowed, else the first allowed. */
     default?: OriginalChoice;
+    /**
+     * The media types this receiver keeps (#2061), exactly, e.g.
+     * `['application/json', 'application/x-ndjson', 'text/xml']`: no wildcards.
+     * For a keep at upload into the receiver's own vault, the upload door
+     * allows these even when the site's attachment allow-list does not
+     * ({@link OriginalKeep}). Every other upload still uses the site's list.
+     */
+    types?: string[];
+}
+/**
+ * What a keep at upload carries to the upload door (#2061): the engine opens
+ * one for one receiver, one user and one call of its `keepOriginal`, and
+ * closes it when the call returns. Pass it on unchanged as the upload's
+ * `keep` option. The door honours only one the engine has open, and only
+ * for a file going into this user's own vault of a system-category the
+ * receiver's add-on declares: there it allows `types` beyond the site's
+ * attachment allow-list, and the file is always served as a download.
+ * Anywhere else it changes nothing.
+ */
+export interface OriginalKeep {
+    /** The receiver keeping, `<slug>.<name>`. */
+    readonly receiver: string;
+    /** The add-on that registered it: only a vault its own system-category declares. */
+    readonly addon: string;
+    /** The user the upload is for: only their own vault. */
+    readonly user: string;
+    /** The receiver's `originals.types`. */
+    readonly types: readonly string[];
 }
 /** A citation to the origin (D11): the receiver renders it, as a footnote on a page. */
 export interface IceCitation {
@@ -180,8 +208,12 @@ export interface IceReceiver {
     /**
      * Keep the original file itself (D11: phr keeps originals in its own
      * store). Without this, `keep` hands the original to the files receiver.
+     * `original.mediaType` is the engine's (#2061): the request's type for a
+     * file uploaded on its own, the engine's for one unpacked from a zip.
+     * `keep` is given for a keep at upload (`keepsEncrypted`): pass it to the
+     * upload door unchanged, as the upload's `keep` option.
      */
-    keepOriginal?(original: IceItem, ctx: ActorContext): Promise<ReceiveOutcome>;
+    keepOriginal?(original: IceItem, ctx: ActorContext, keep?: OriginalKeep): Promise<ReceiveOutcome>;
     /**
      * `keepOriginal` writes into an encrypted store (phr's vault), which only a
      * request holding the user's unlocked key can write (#2034). The engine then

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

@@ -10,7 +10,8 @@ import type { WikiEngine } from '../types/WikiEngine.js';
 import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, SchemaType, RebuildOpts } from '../types/Schema.js';
 import type { User } from '../providers/BaseAttachmentProvider.js';
 import { type AssetQuery, type AssetRecord } from '../types/Asset.js';
-import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
+import type { StoreFileEntry, StoreFileInput, StoreFileLocation } from '../types/Provider.js';
+import type { OriginalKeep } from '../ice/types.js';
 /**
  * Base attachment provider interface
  */
@@ -44,13 +45,7 @@ interface BaseAttachmentProvider {
     getProviderInfo(): {
         features: string[];
     };
-    storeFileInStore(location: StoreFileLocation, bytes: Buffer, file: {
-        originalName: string;
-        mimeType: string;
-        description: string;
-        author?: string;
-        pageName?: string;
-    }): Promise<StoreFileEntry>;
+    storeFileInStore(location: StoreFileLocation, bytes: Buffer, file: StoreFileInput): Promise<StoreFileEntry>;
     getFileInStore(location: StoreFileLocation, id: string): Promise<{
         entry: StoreFileEntry;
         bytes: Buffer;
@@ -104,6 +99,15 @@ export interface UploadOptions {
     private?: boolean;
     /** Store id when private with no private page; default from ConfigurationManager defaultstoreid */
     store?: string;
+    /**
+     * An import's keep at upload (#2061): the `OriginalKeep` the engine handed
+     * the receiver's `keepOriginal`, passed on unchanged. Honoured only while
+     * the engine holds it open, for a file going into its user's own vault of a
+     * system-category the receiver's add-on declares: there the receiver's
+     * declared types are allowed beyond the site's allow-list, and the file is
+     * served as a download. Anywhere else it changes nothing.
+     */
+    keep?: OriginalKeep;
 }
 /**
  * Mention object (WebPage reference)

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

@@ -282,6 +282,14 @@ declare class BackgroundJobManager extends BaseManager {
     private compileScheduled;
     /** A run's time limit: the job's own, else `fallback`, capped by `ngdpbase.jobs.max-timeout-ms` when set. */
     private timeoutFor;
+    /**
+     * The time zone the scheduler runs a schedule in when the schedule names
+     * none (#1998): `ngdpbase.default.timezone`, UTC when it is not set. Read
+     * each call, as the schedules are. An add-on's job passes it, with its
+     * `ctx.slot`, to `host.zonedParts` to learn the slot's local month or day.
+     * A schedule that names its own `tz` runs in that zone instead.
+     */
+    scheduleTimeZone(): string;
     private compile;
     /**
      * `ngdpbase.jobs.<id>.schedule` in place of the registered schedule. One

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

@@ -267,7 +267,8 @@ export type TakeoutImportReport = {
 export interface UsableReceiver {
     id: string;
     label?: string;
-    originals: Required<IceOriginalChoices>;
+    /** What the screen offers; the kept types (`types`, #2061) are the upload door's business, not the screen's. */
+    originals: Required<Omit<IceOriginalChoices, 'types'>>;
 }
 /**
  * Import Manager class
@@ -546,10 +547,6 @@ declare class ImportManager extends BaseManager {
      * @returns Stats about imported attachments
      */
     private importPageAttachments;
-    /**
-     * Get MIME type from file extension
-     */
-    private getMimeType;
     /**
      * Get file extensions to process based on options
      */

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

@@ -34,6 +34,13 @@ interface AccessContext {
  * policy naming it decides nothing (docs/access-policies.md).
  */
 export declare const RESOURCE_MATCHERS: Record<string, (pattern: string, pageName: string, attributes?: ResourceAttributes) => boolean>;
+/**
+ * How each policy subject type matches (#1999), one matcher per type. These
+ * are the only subject types a decision matches, and the only ones
+ * PolicyValidator accepts: a type with no matcher here would be a policy that
+ * grants nothing.
+ */
+export declare const SUBJECT_MATCHERS: Record<string, (value: string, userContext: UserContext | undefined) => boolean>;
 /**
  * The resource types configuration declares (#1504), for the evaluator and the
  * validator alike. When the key is not set at all — a configuration older than

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

@@ -132,6 +132,8 @@ export interface JobSubject {
     viaToken?: AgentTokenGrant;
     viaShare?: ShareGrant;
     viaProxy?: ProxyClaim;
+    /** #1999: the scheduled job a run acts as (`JobContext.job`). */
+    job?: string;
 }
 /**
  * User creation input data

package/lib/src/providers/BaseAttachmentProvider.d.ts

@@ -1,5 +1,5 @@
 import { AttachmentMetadata, AttachmentProvider } from '../types/index.js';
-import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
+import type { StoreFileEntry, StoreFileInput, StoreFileLocation } from '../types/Provider.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { ProviderInfo } from './BasePageProvider.js';
 import BaseProvider from './BaseProvider.js';
@@ -150,13 +150,7 @@ declare abstract class BaseAttachmentProvider extends BaseProvider implements At
      */
     getAttachmentByFilename(_filename: string): Promise<AttachmentMetadata | null>;
     /** Store a file in a store. The same bytes already in THAT store return the existing entry. */
-    storeFileInStore(_location: StoreFileLocation, _bytes: Buffer, _file: {
-        originalName: string;
-        mimeType: string;
-        description: string;
-        author?: string;
-        pageName?: string;
-    }): Promise<StoreFileEntry>;
+    storeFileInStore(_location: StoreFileLocation, _bytes: Buffer, _file: StoreFileInput): Promise<StoreFileEntry>;
     /** One file of a store, with its bytes; null when the store does not list it. */
     getFileInStore(_location: StoreFileLocation, _id: string): Promise<{
         entry: StoreFileEntry;

package/lib/src/providers/BasicAttachmentProvider.d.ts

@@ -1,5 +1,5 @@
 import BaseAttachmentProvider, { FileInfo, User, AttachmentResult } from './BaseAttachmentProvider.js';
-import type { ProviderInfo, StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
+import type { ProviderInfo, StoreFileEntry, StoreFileInput, StoreFileLocation } from '../types/Provider.js';
 import { AttachmentMetadata } from '../types/index.js';
 import type { AssetProvider, AssetRecord, AssetQuery, AssetPage, AssetInput, AssetMetadata, AssetMetadataPatch } from '../types/Asset.js';
 import type { CreativeWork } from '../types/Schema.js';
@@ -213,6 +213,7 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
     /**
      * Validate file against constraints
      * @param fileInfo - File information
+     * @param alsoAllowed - Types allowed beyond the site's list: only an import's kept original into its receiver's own vault (#2061)
      * @private
      */
     private validateFile;
@@ -261,13 +262,7 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
     private requirePagesDirectory;
     private readStoreIndex;
     private writeStoreIndex;
-    storeFileInStore(location: StoreFileLocation, bytes: Buffer, file: {
-        originalName: string;
-        mimeType: string;
-        description: string;
-        author?: string;
-        pageName?: string;
-    }): Promise<StoreFileEntry>;
+    storeFileInStore(location: StoreFileLocation, bytes: Buffer, file: StoreFileInput): Promise<StoreFileEntry>;
     getFileInStore(location: StoreFileLocation, id: string): Promise<{
         entry: StoreFileEntry;
         bytes: Buffer;

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

@@ -59,6 +59,14 @@ export declare class PolicyDecisionPoint extends BaseManager {
      *   not something to resolve silently here.
      */
     policies(): Policy[];
+    /**
+     * Whether a policy in force names the scheduled job `jobId` as a subject
+     * (`{ "type": "job", "value": jobId }`, #1999), allow or deny. When one
+     * does, the job's runs act as the job itself; when none does, as the system
+     * principal. Read live, so a site that removes the policy gives the job the
+     * system roles back at its next decision.
+     */
+    namesJob(jobId: string): boolean;
     /**
      * What each role permits: role name → the actions its holders are granted.
      *

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

@@ -178,7 +178,7 @@ declare class PolicyInformationPoint extends BaseManager {
      * resolves to the anonymous subject: the job then holds exactly what a
      * visitor holds, which is the safe answer for someone who no longer exists.
      */
-    resolveSubjectNow(username: string | undefined): Promise<UserContext>;
+    resolveSubjectNow(username: string | undefined, job?: string): 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

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

@@ -12,9 +12,9 @@
  * again because a `.d.ts` may not import a `.ts`. Four copies of one shape is
  * how a field gets added to one and missed in the others.
  */
-/** Who a policy grants to. `role` is the only type the evaluator matches today. */
+/** Who a policy grants to. The evaluator matches `role` and `job` (#1999), its `SUBJECT_MATCHERS`. */
 export interface PolicySubject {
-    /** `role`, and in future `user` or `group`. */
+    /** `role`, or `job` for a scheduled job acting as itself (#1999). */
     type: string;
     value: string;
 }

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

@@ -582,6 +582,27 @@ export interface StoreFileEntry {
     dateModified: string;
     /** Pages the file was uploaded onto. */
     mentions: string[];
+    /**
+     * An import's kept original (#2061): always served as a download
+     * (`Content-Disposition: attachment`, `nosniff`), never shown inline.
+     */
+    download?: true;
+}
+/** What `storeFileInStore` is told about a file it stores in a private store. */
+export interface StoreFileInput {
+    originalName: string;
+    mimeType: string;
+    description: string;
+    author?: string;
+    pageName?: string;
+    /**
+     * Set only by AttachmentManager for an import's keep into the receiver's
+     * own vault (#2061): `types` are allowed beyond the site's allow-list, and
+     * the file is marked {@link StoreFileEntry.download}.
+     */
+    keptOriginal?: {
+        types: readonly string[];
+    };
 }
 /**
  * A page in a private store (#1456): its entry in the store's OWN page index,

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

@@ -51,6 +51,11 @@
  * classify only its own keys, `ngdpbase.addons.<slug>` and what is under it
  * (paths inside its values included). An entry for any other key refuses the
  * addon, since it could unhide core's or another addon's secret.
+ *
+ * A fifth, `ngdpbase.access.policies` job subjects (#1999): an enabled addon's
+ * policy may name only its own scheduled jobs, `{ "type": "job", "value":
+ * "<slug>.<job>" }`. A policy naming core's job or another addon's refuses
+ * the addon, since it would grant that job permissions its owner never chose.
  */
 import { type AddonDatabaseDeclaration } from './addonDatabaseRules.js';
 export declare const ADDONS_PATH_KEY = "ngdpbase.managers.addons-manager.addons-path";
@@ -119,6 +124,17 @@ export interface AddonSensitiveValuesLayer {
  * enabled addon's entries reach the merge, so only an enabled addon is checked.
  */
 export declare function addonSensitiveValuesLayer(addons: readonly AddonDefaults[]): AddonSensitiveValuesLayer;
+export interface AddonJobPolicyLayer {
+    /** Addons whose policies name a job that is not their own, by slug, with why: never loaded. */
+    refused: Map<string, string>;
+    problems: string[];
+}
+/**
+ * Which jobs an addon's policies may name (#1999): its own, ids starting
+ * `<slug>.`, the prefix its job ids carry. Only an enabled addon's policies
+ * reach the merge, so only an enabled addon is checked.
+ */
+export declare function addonJobPolicyLayer(addons: readonly AddonDefaults[]): AddonJobPolicyLayer;
 /** The configuration key that makes an addon site-critical (#1883). */
 export declare function addonSiteCriticalKey(slug: string): string;
 export interface AddonSiteCriticalLayer {

package/lib/src/utils/addonConfigLayer.js

@@ -51,6 +51,11 @@
  * classify only its own keys, `ngdpbase.addons.<slug>` and what is under it
  * (paths inside its values included). An entry for any other key refuses the
  * addon, since it could unhide core's or another addon's secret.
+ *
+ * A fifth, `ngdpbase.access.policies` job subjects (#1999): an enabled addon's
+ * policy may name only its own scheduled jobs, `{ "type": "job", "value":
+ * "<slug>.<job>" }`. A policy naming core's job or another addon's refuses
+ * the addon, since it would grant that job permissions its owner never chose.
  */
 import fs from 'fs';
 import path from 'path';
@@ -313,6 +318,37 @@ export function addonSensitiveValuesLayer(addons) {
     }
     return layer;
 }
+/**
+ * Which jobs an addon's policies may name (#1999): its own, ids starting
+ * `<slug>.`, the prefix its job ids carry. Only an enabled addon's policies
+ * reach the merge, so only an enabled addon is checked.
+ */
+export function addonJobPolicyLayer(addons) {
+    const layer = { refused: new Map(), problems: [] };
+    for (const addon of addons) {
+        if (!addon.enabled)
+            continue;
+        const policies = addon.defaults['ngdpbase.access.policies'];
+        if (!Array.isArray(policies))
+            continue;
+        const foreign = [];
+        for (const policy of policies) {
+            const subjects = isPlainObject(policy) && Array.isArray(policy.subjects) ? policy.subjects : [];
+            for (const subject of subjects) {
+                if (!isPlainObject(subject) || subject.type !== 'job')
+                    continue;
+                if (typeof subject.value !== 'string' || !subject.value.startsWith(`${addon.slug}.`))
+                    foreign.push(`'${String(subject.value)}' (policy '${String(policy.id)}')`);
+            }
+        }
+        if (foreign.length === 0)
+            continue;
+        const reason = `its policies name the job(s) ${foreign.join(', ')}, which are not its own; an add-on's policy names only its own jobs, ${addon.slug}.<job>`;
+        layer.refused.set(addon.slug, reason);
+        layer.problems.push(`${addonProblemSubject(addon.slug, addon.enabled)}: ${reason}; the add-on is not loaded`);
+    }
+    return layer;
+}
 /** The configuration key that makes an addon site-critical (#1883). */
 export function addonSiteCriticalKey(slug) {
     return `ngdpbase.addons.${slug}.site-critical`;
@@ -402,9 +438,10 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
     const databaseLayer = addonDatabaseLayer(addons, custom);
     const criticalLayer = addonSiteCriticalLayer(addons, custom);
     const sensitiveLayer = addonSensitiveValuesLayer(addons);
+    const jobPolicyLayer = addonJobPolicyLayer(addons);
     const siteCritical = criticalLayer.siteCritical;
     const refused = new Map(layer.refused);
-    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused, ...sensitiveLayer.refused])
+    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused, ...sensitiveLayer.refused, ...jobPolicyLayer.refused])
         refused.set(slug, refused.has(slug) ? `${refused.get(slug)}; ${reason}` : reason);
     const databases = databaseLayer.declarations.map((d) => ({ ...d, enabled: d.enabled && !refused.has(d.declaredBy) }));
     const withAddons = addons
@@ -418,14 +455,14 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
         return deepMergeObjects(acc, rest);
     }, shipped);
     if (Object.keys(layer.entries).length === 0) {
-        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems], refused, databases, siteCritical };
+        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems, ...jobPolicyLayer.problems], refused, databases, siteCritical };
     }
     const shippedCategories = isPlainObject(withAddons[SYSTEM_CATEGORY_KEY]) ? withAddons[SYSTEM_CATEGORY_KEY] : {};
     const layered = { ...withAddons, [SYSTEM_CATEGORY_KEY]: deepMergeObjects(shippedCategories, layer.entries) };
     const merged = deepMergeObjects(layered, custom);
     const stood = ownerDeclarationsStand(merged[SYSTEM_CATEGORY_KEY], layer, customCategories);
     merged[SYSTEM_CATEGORY_KEY] = stood.categories;
-    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems], refused, databases, siteCritical };
+    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems, ...jobPolicyLayer.problems], refused, databases, siteCritical };
 }
 /**
  * The full merge for a caller with the two files already read (the manager,

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

@@ -18,9 +18,11 @@
  * - `registerShim` and `registerReceiver` (#1979, ICE) register into the import
  *   engine under this add-on's slug, and only the names its manifest declares;
  * - the egress tools (`resolveEgressPolicy`, `validateUrl`,
- *   `createGuardedElasticsearchClient`, `refusedNodeMessage`) and `isAtLeast`
- *   are core's own pure functions, handed on unchanged, so an add-on never
- *   imports them from `dist/` (#1813);
+ *   `createGuardedElasticsearchClient`, `refusedNodeMessage`), `isAtLeast`
+ *   and `zonedParts` (#1998) are core's own pure functions, handed on
+ *   unchanged, so an add-on never imports them from `dist/` (#1813);
+ * - `keyedSerial()` returns a new `KeyedSerial`, core's own per-key queue, so
+ *   an add-on's manager changes each of its records one at a time (#2065);
  * - the object is `Object.freeze`d, so no add-on can replace a value.
  *
  * Additive only: nothing here is removed or renamed without a major release.
@@ -36,6 +38,8 @@ import { resolveEgressPolicy } from '../http/egressPolicy.js';
 import { validateUrl } from '../http/ssrf.js';
 import { createGuardedElasticsearchClient, refusedNodeMessage } from '../http/guardedElasticsearch.js';
 import { isAtLeast } from './version.js';
+import { zonedParts } from './availability.js';
+import { KeyedSerial } from './keyedSerial.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 import type { IceReceiver, IceShim } from '../ice/types.js';
@@ -80,6 +84,20 @@ export interface AddonHost {
     readonly refusedNodeMessage: typeof refusedNodeMessage;
     /** Whether an `x.y.z` version is at least another; throws on a version that is not `x.y.z`. */
     readonly isAtLeast: typeof isAtLeast;
+    /**
+     * #1998: an instant in a named time zone, as its local parts: `year`,
+     * `month` (1–12), `date` (`YYYY-MM-DD`), `day` (weekday name) and `minutes`
+     * since midnight. A scheduled job passes its `ctx.slot` and
+     * `BackgroundJobManager.scheduleTimeZone()` to learn which local month or
+     * day the slot falls in. An unknown zone answers in UTC.
+     */
+    readonly zonedParts: typeof zonedParts;
+    /**
+     * #2065: a new `KeyedSerial` (core's own) at each call; take one per manager.
+     * Run each read-modify-write of one of your records inside `run(recordId, fn)`,
+     * the read included. Not re-entrant: `fn` must not `run` the same key again.
+     */
+    readonly keyedSerial: () => KeyedSerial;
     /**
      * #1979 (ICE, D6): register an import shim, as `<slug>.<shim.name>`. Call it
      * in `register`. Refused when the manifest's `shims` does not name it.

package/lib/src/utils/addonHost.js

@@ -18,9 +18,11 @@
  * - `registerShim` and `registerReceiver` (#1979, ICE) register into the import
  *   engine under this add-on's slug, and only the names its manifest declares;
  * - the egress tools (`resolveEgressPolicy`, `validateUrl`,
- *   `createGuardedElasticsearchClient`, `refusedNodeMessage`) and `isAtLeast`
- *   are core's own pure functions, handed on unchanged, so an add-on never
- *   imports them from `dist/` (#1813);
+ *   `createGuardedElasticsearchClient`, `refusedNodeMessage`), `isAtLeast`
+ *   and `zonedParts` (#1998) are core's own pure functions, handed on
+ *   unchanged, so an add-on never imports them from `dist/` (#1813);
+ * - `keyedSerial()` returns a new `KeyedSerial`, core's own per-key queue, so
+ *   an add-on's manager changes each of its records one at a time (#2065);
  * - the object is `Object.freeze`d, so no add-on can replace a value.
  *
  * Additive only: nothing here is removed or renamed without a major release.
@@ -35,6 +37,8 @@ import { resolveEgressPolicy } from '../http/egressPolicy.js';
 import { validateUrl } from '../http/ssrf.js';
 import { createGuardedElasticsearchClient, refusedNodeMessage } from '../http/guardedElasticsearch.js';
 import { isAtLeast } from './version.js';
+import { zonedParts } from './availability.js';
+import { KeyedSerial } from './keyedSerial.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 import { auditDeclarationsFrom } from './auditRegistry.js';
@@ -117,6 +121,8 @@ export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPers
         validateUrl,
         createGuardedElasticsearchClient,
         refusedNodeMessage,
-        isAtLeast
+        isAtLeast,
+        zonedParts,
+        keyedSerial: () => new KeyedSerial()
     });
 }

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

@@ -0,0 +1,120 @@
+/**
+ * Is the instance open to ordinary traffic, and if not, why (#1432)?
+ *
+ * "Is the site open" is not "may this identity do this". The second is the
+ * permission door; this is the first, and it has several reasons — maintenance,
+ * a schedule such as business hours, and a holiday. They shared one property:
+ * the configuration shipped switches for all of them and only maintenance was
+ * ever enforced, so an operator could turn business hours on and nothing
+ * happened. `PolicyInformationPoint` carried the unreachable implementations
+ * (`checkBusinessHours`, `checkHolidayRestrictions`, `checkEnhancedTimeRestrictions`),
+ * which is also the wrong manager for the question.
+ *
+ * One resolver, one gate, one dialog, different messages. This returns the
+ * FIRST reason that closes the instance, with the operator's own wording for
+ * it, and the gate middleware renders it.
+ *
+ * Read per request, never cached at boot, so an admin toggle takes effect
+ * without a restart. Maintenance itself is `MaintenanceState`'s (#1906): the
+ * gate passes its visitor view in, and this only ranks it first.
+ */
+import type { MaintenanceVisitorView } from './maintenanceState.js';
+/**
+ * Read one configuration value. No fallback parameter, deliberately.
+ *
+ * A fallback in the call is a second place the value can come from, and it is
+ * invisible to the operator: the shipped `config/app-default-config.json` can
+ * lose a key and nothing says so, because the caller quietly supplied one.
+ * Every key this module reads IS declared there, so absence means a broken
+ * configuration, not a value to invent.
+ *
+ * What this module does with an absent value:
+ *
+ * - __a switch__ (`…enabled`) reads as OFF, and says so in the log. A missing
+ *   switch must never CLOSE the instance — that would lock everyone out over a
+ *   typo — but it is still reported rather than assumed.
+ * - __a window, schedule or holiday map__ absent means nothing to enforce.
+ * - __a message__ falls back to a constant, because something has to render on
+ *   the page. That is the only fallback here, and it is display text.
+ */
+export type ReadProperty = (key: string) => unknown;
+/** Which reason closed the instance. */
+export type AvailabilityKind = 'maintenance' | 'schedule' | 'holiday' | 'misconfigured';
+export interface AvailabilityState {
+    /** Whether ordinary traffic is refused. */
+    blocked: boolean;
+    /** Which reason closed it; null when open. */
+    kind: AvailabilityKind | null;
+    /** Shown on the page. Never empty when blocked. */
+    message: string;
+    /** Whether an administrator may still reach the instance. */
+    allowAdmins: boolean;
+    /** Operator-supplied estimate, maintenance only. */
+    estimatedDuration: string | null;
+}
+export declare const BUSINESS_HOURS_ENABLED_KEY = "ngdpbase.access-control.business-hours.enabled";
+export declare const BUSINESS_HOURS_MESSAGE_KEY = "ngdpbase.access-control.business-hours.message";
+export declare const CUSTOM_SCHEDULES_ENABLED_KEY = "ngdpbase.access-control.custom-schedules.enabled";
+export declare const CUSTOM_SCHEDULES_FILE_KEY = "ngdpbase.access-control.custom-schedules.schedules";
+export declare const SCHEDULES_KEY = "ngdpbase.schedules";
+export declare const HOLIDAYS_ENABLED_KEY = "ngdpbase.holidays.enabled";
+export declare const HOLIDAYS_DATES_KEY = "ngdpbase.holidays.dates";
+export declare const HOLIDAYS_MESSAGE_KEY = "ngdpbase.holidays.message";
+export declare const TIME_ZONE_KEY = "ngdpbase.time-zone";
+/** A named schedule from `ngdpbase.schedules`. */
+export interface ScheduleRule {
+    days?: string[];
+    startTime?: string;
+    endTime?: string;
+    /** `allow` opens the window; `deny` closes it. Absent reads as `allow`. */
+    type?: string;
+}
+export interface Schedule {
+    name?: string;
+    description?: string;
+    timeZone?: string;
+    rules?: ScheduleRule[];
+    exceptions?: string[];
+    enabled?: boolean;
+    message?: string;
+}
+/** A holiday entry. The key carries the date — `2026-07-04` or `*-12-25`. */
+export interface HolidayEntry {
+    name?: string;
+    message?: string;
+    enabled?: boolean;
+}
+/**
+ * The instant, in a named time zone, as the parts a schedule compares:
+ * the weekday and minutes since midnight, plus the ISO date for a holiday,
+ * and the local year and month (1–12), which a month boundary needs (#1998).
+ * An add-on reaches it as `host.zonedParts`.
+ *
+ * Uses `Intl` rather than arithmetic on the epoch so daylight saving is the
+ * platform's problem, not ours.
+ */
+export declare function zonedParts(now: Date, timeZone: string): {
+    day: string;
+    minutes: number;
+    date: string;
+    year: number;
+    month: number;
+};
+/**
+ * Whether a schedule is open at `now`.
+ *
+ * A `deny` rule matching the day closes it outright. Otherwise an `allow` rule
+ * must match both the day and the time window. A schedule with no rules is
+ * open — an empty schedule is not a lockout.
+ */
+export declare function scheduleIsOpen(schedule: Schedule, now: Date, fallbackZone: string): boolean;
+/** Whether `date` (ISO `YYYY-MM-DD`) matches a holiday key, including `*-MM-DD`. */
+export declare function holidayKeyMatches(key: string, date: string): boolean;
+/**
+ * The first reason the instance is closed, or an open state.
+ *
+ * Order is maintenance, then schedule, then holiday: the operator's own switch
+ * before anything time-based, so "I closed it" is never reported as "it is a
+ * holiday".
+ */
+export declare function resolveAvailability(get: ReadProperty, now?: Date, maintenance?: MaintenanceVisitorView | null): AvailabilityState;

package/lib/src/utils/availability.js

@@ -0,0 +1,174 @@
+'use strict';
+export const BUSINESS_HOURS_ENABLED_KEY = 'ngdpbase.access-control.business-hours.enabled';
+export const BUSINESS_HOURS_MESSAGE_KEY = 'ngdpbase.access-control.business-hours.message';
+export const CUSTOM_SCHEDULES_ENABLED_KEY = 'ngdpbase.access-control.custom-schedules.enabled';
+export const CUSTOM_SCHEDULES_FILE_KEY = 'ngdpbase.access-control.custom-schedules.schedules';
+export const SCHEDULES_KEY = 'ngdpbase.schedules';
+export const HOLIDAYS_ENABLED_KEY = 'ngdpbase.holidays.enabled';
+export const HOLIDAYS_DATES_KEY = 'ngdpbase.holidays.dates';
+export const HOLIDAYS_MESSAGE_KEY = 'ngdpbase.holidays.message';
+export const TIME_ZONE_KEY = 'ngdpbase.time-zone';
+const DEFAULT_SCHEDULE_MESSAGE = 'The site is closed at this time. Please try again during opening hours.';
+const DEFAULT_HOLIDAY_MESSAGE = 'The site is closed for a holiday. Please try again later.';
+function toBoolean(value, fallback) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === 'true')
+            return true;
+        if (normalized === 'false')
+            return false;
+        return fallback;
+    }
+    if (typeof value === 'number')
+        return value !== 0;
+    return fallback;
+}
+function text(value, fallback) {
+    return typeof value === 'string' && value.trim() !== '' ? value : fallback;
+}
+/**
+ * The instant, in a named time zone, as the parts a schedule compares:
+ * the weekday and minutes since midnight, plus the ISO date for a holiday,
+ * and the local year and month (1–12), which a month boundary needs (#1998).
+ * An add-on reaches it as `host.zonedParts`.
+ *
+ * Uses `Intl` rather than arithmetic on the epoch so daylight saving is the
+ * platform's problem, not ours.
+ */
+export function zonedParts(now, timeZone) {
+    let parts;
+    try {
+        parts = new Intl.DateTimeFormat('en-US', {
+            timeZone,
+            hour12: false,
+            weekday: 'long',
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit'
+        }).formatToParts(now);
+    }
+    catch {
+        // An unknown zone must not decide the site is closed: fall back to UTC.
+        return zonedParts(now, 'UTC');
+    }
+    const find = (type) => parts.find((p) => p.type === type)?.value ?? '';
+    const hour = Number(find('hour'));
+    return {
+        day: find('weekday').toLowerCase(),
+        // Intl renders midnight as 24 in some locales with hour12:false.
+        minutes: (hour === 24 ? 0 : hour) * 60 + Number(find('minute')),
+        date: `${find('year')}-${find('month')}-${find('day')}`,
+        year: Number(find('year')),
+        month: Number(find('month'))
+    };
+}
+function minutesOf(hhmm) {
+    if (typeof hhmm !== 'string')
+        return null;
+    const match = /^(\d{1,2}):(\d{2})$/.exec(hhmm.trim());
+    if (!match)
+        return null;
+    const hours = Number(match[1]);
+    const mins = Number(match[2]);
+    if (hours > 23 || mins > 59)
+        return null;
+    return hours * 60 + mins;
+}
+/**
+ * Whether a schedule is open at `now`.
+ *
+ * A `deny` rule matching the day closes it outright. Otherwise an `allow` rule
+ * must match both the day and the time window. A schedule with no rules is
+ * open — an empty schedule is not a lockout.
+ */
+export function scheduleIsOpen(schedule, now, fallbackZone) {
+    const rules = Array.isArray(schedule.rules) ? schedule.rules : [];
+    if (rules.length === 0)
+        return true;
+    const { day, minutes } = zonedParts(now, text(schedule.timeZone, fallbackZone));
+    const matchesDay = (rule) => {
+        if (!Array.isArray(rule.days) || rule.days.length === 0)
+            return true;
+        return rule.days.some((d) => typeof d === 'string' && d.trim().toLowerCase() === day);
+    };
+    for (const rule of rules) {
+        if (rule.type === 'deny' && matchesDay(rule))
+            return false;
+    }
+    let sawAllow = false;
+    for (const rule of rules) {
+        if (rule.type === 'deny')
+            continue;
+        sawAllow = true;
+        if (!matchesDay(rule))
+            continue;
+        const start = minutesOf(rule.startTime);
+        const end = minutesOf(rule.endTime);
+        if (start === null || end === null)
+            return true; // a malformed window does not close the site
+        if (start <= end ? minutes >= start && minutes < end : minutes >= start || minutes < end)
+            return true;
+    }
+    return !sawAllow;
+}
+/** Whether `date` (ISO `YYYY-MM-DD`) matches a holiday key, including `*-MM-DD`. */
+export function holidayKeyMatches(key, date) {
+    if (key === date)
+        return true;
+    if (key.startsWith('*-'))
+        return date.slice(5) === key.slice(2);
+    return false;
+}
+/**
+ * The first reason the instance is closed, or an open state.
+ *
+ * Order is maintenance, then schedule, then holiday: the operator's own switch
+ * before anything time-based, so "I closed it" is never reported as "it is a
+ * holiday".
+ */
+export function resolveAvailability(get, now = new Date(), maintenance = null) {
+    // #1906: `engine.maintenance.visitorView(…)`, null when the site is not in
+    // maintenance mode. Its message is already the one visitors may see.
+    if (maintenance) {
+        return {
+            blocked: true,
+            kind: 'maintenance',
+            message: maintenance.message,
+            allowAdmins: maintenance.adminsMayEnter,
+            estimatedDuration: maintenance.estimatedDuration
+        };
+    }
+    const open = {
+        blocked: false, kind: null, message: '', allowAdmins: true, estimatedDuration: null
+    };
+    const fallbackZone = text(get(TIME_ZONE_KEY), 'UTC');
+    // An administrator can always reach a time-closed instance: a schedule that
+    // locks out the only person who can change it is a trap, and unlike
+    // maintenance there is no switch to flip from outside.
+    const closed = (kind, message) => ({
+        blocked: true, kind, message, allowAdmins: true, estimatedDuration: null
+    });
+    const schedules = (get(SCHEDULES_KEY) ?? {});
+    if (toBoolean(get(BUSINESS_HOURS_ENABLED_KEY), false)) {
+        const schedule = schedules['business-hours'];
+        if (schedule && toBoolean(schedule.enabled, true) && !scheduleIsOpen(schedule, now, fallbackZone)) {
+            return closed('schedule', text(schedule.message ?? get(BUSINESS_HOURS_MESSAGE_KEY), DEFAULT_SCHEDULE_MESSAGE));
+        }
+    }
+    if (toBoolean(get(HOLIDAYS_ENABLED_KEY), false)) {
+        const dates = (get(HOLIDAYS_DATES_KEY) ?? {});
+        const { date } = zonedParts(now, fallbackZone);
+        for (const [key, entry] of Object.entries(dates)) {
+            if (!entry || !toBoolean(entry.enabled, true))
+                continue;
+            if (!holidayKeyMatches(key, date))
+                continue;
+            return closed('holiday', text(entry.message ?? get(HOLIDAYS_MESSAGE_KEY), DEFAULT_HOLIDAY_MESSAGE));
+        }
+    }
+    return open;
+}

package/lib/src/utils/keyedSerial.js

@@ -0,0 +1,41 @@
+/**
+ * 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 class KeyedSerial {
+    /** The settled tail of each key's queue: never rejects. */
+    tails = new Map();
+    /** Run `task` after every earlier task on `key` has settled; resolves or rejects as `task` does. */
+    run(key, task) {
+        const before = this.tails.get(key) ?? Promise.resolve();
+        const result = before.then(task);
+        const tail = result.then(() => undefined, () => undefined);
+        this.tails.set(key, tail);
+        void tail.then(() => { if (this.tails.get(key) === tail)
+            this.tails.delete(key); });
+        return result;
+    }
+    /** Resolves once every task queued so far, on every key, has settled (shutdown). */
+    async settled() {
+        await Promise.all([...this.tails.values()]);
+    }
+}
+export default KeyedSerial;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.30.0",
+  "version": "5.30.1",
   "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",