@jwilleke/ngdpbase-types 5.30.0 → 5.31.0

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

@@ -17,15 +17,40 @@
  */
 import type { PostalAddress, ContactPointEntry } from './Organization.js';
 /**
- * One organization a person is affiliated with (#1930): schema.org
- * `affiliation`, with the person's role or title there when one is known.
+ * One affiliation of a digital identity (#2039): schema.org `affiliation`
+ * with an `OrganizationRole`, as the identity model says
+ * (`docs/planning/identity-model.md`, "Affiliation shape"). It puts the
+ * identity in a group, the organization plus the title, and never grants a
+ * permission.
+ *
  * The organization is named by its `@id`; OrganizationManager lists an
  * organization's people by reading these, so the link is stored once, here.
+ * With the site's own organization it is a fact, set only under
+ * `identity-manage`; with any other it is a claim, which a user may also set
+ * on their own identity record. IdentityManager's door decides.
  */
 export interface PersonAffiliation {
-    /** The organization's `@id`. */
+    '@type': 'OrganizationRole';
+    /** The organization, by its `@id`. */
+    memberOf: {
+        '@id': string;
+    };
+    /** The affiliation's title there (Owner, Treasurer, Vendor): free text, never a Role. Left out when none is known. */
+    roleName?: string;
+    /** ISO date (`YYYY-MM-DD`) the affiliation began; left out when not known. */
+    startDate?: string;
+    /** ISO date (`YYYY-MM-DD`) it ended or ends, the day included; left out while it is ongoing. */
+    endDate?: string;
+}
+/**
+ * An affiliation in its shape before #2039, `{ organization, role? }`.
+ * Converted (organization → `memberOf`, role → `roleName`) when read, once on
+ * disk at start-up, and when an add-on still writes it (for one release).
+ *
+ * @deprecated Write {@link PersonAffiliation}.
+ */
+export interface LegacyPersonAffiliation {
     organization: string;
-    /** The person's role or title there (schema.org `roleName`), when known. */
     role?: string;
 }
 /**
@@ -59,7 +84,7 @@ export interface Person {
     image?: string;
     /** Other URLs that identify this person (LinkedIn, GitHub, etc.) */
     sameAs?: string[];
-    /** Organizations this person is affiliated with, each with an optional role (#1930). */
+    /** Affiliations: each a schema.org OrganizationRole, an organization with a title and dates (#2039). */
     affiliation?: PersonAffiliation[];
     /** Allow extension fields (additionalProperty, etc.) */
     [key: string]: unknown;
@@ -69,12 +94,20 @@ export interface Person {
  * `@context`/`@type` are immutable; `@id` and `identifier` cannot be changed via update.
  */
 export type PersonUpdate = Partial<Omit<Person, '@context' | '@type' | '@id' | 'identifier'>>;
+/**
+ * What `IdentityManager.update` takes: a {@link PersonUpdate} whose
+ * `affiliation` (the whole list) may still hold entries in the old
+ * `{ organization, role? }` shape, converted at the door, for one release (#2039).
+ */
+export type PersonChange = Omit<PersonUpdate, 'affiliation'> & {
+    affiliation?: Array<PersonAffiliation | LegacyPersonAffiliation>;
+};
 /**
  * What a caller gives `IdentityManager.create` (#1930): the person's fields.
  * `identifier` is left out for a person with no account (one is generated);
  * UserManager passes the account's username when it creates the person for a
  * new account.
  */
-export type PersonInput = PersonUpdate & {
+export type PersonInput = PersonChange & {
     identifier?: string;
 };

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;