@jwilleke/ngdpbase-types 5.21.0 → 5.22.0

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

@@ -12,6 +12,14 @@
  * Implements the MailProvider interface so it can be passed directly to
  * MagicLinkAuthProvider without any changes to that class.
  *
+ * A failed send is never silent (#1916). Every sender goes through `send()`,
+ * so it is reported here, once for all of them: logged (provider, recipient
+ * domain, subject, error — never the body or the full address), the manager
+ * shows degraded until the next send succeeds, and administrators get one
+ * notification per `ngdpbase.mail.failure-notice.window-minutes` carrying a
+ * running count, not one per email. `send()` still rejects, so a caller with
+ * a person waiting can tell them.
+ *
  * @see docs/admin/email-setup.md for operator setup instructions
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/456}
  */
@@ -19,21 +27,55 @@ import BaseManager from './BaseManager.js';
 import type { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { MailMessage, MailProvider } from '../mail/MailProvider.js';
+/** The degraded reason while sends fail; cleared by the next success. */
+export declare const SEND_FAILING_REASON = "outbound email is failing \u2014 see the server log and the administrator notification";
+/** Title of the administrator notice. */
+export declare const SEND_FAILING_TITLE = "Email could not be sent";
 declare class EmailManager extends BaseManager implements MailProvider {
     private provider;
     private providerName;
     private from;
     private enabled;
+    private noticeWindowMs;
+    private notice;
+    private failuresSinceSuccess;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /**
      * Send an email. Injects the configured from address if the message omits it.
+     *
+     * A failure is reported here (#1916) and then rethrown, so a caller with a
+     * person waiting can tell them it was not sent.
      */
     send(message: MailMessage): Promise<void>;
     /**
      * Convenience wrapper — build and send a message in one call.
      */
     sendTo(to: string, subject: string, text: string, html?: string): Promise<void>;
+    /**
+     * Send without waiting, for a sender nobody is waiting on (a form's copy, a
+     * reservation notice). Never rejects: a failure is already logged and
+     * reported to administrators by `send()` (#1916), so there is nothing left
+     * for the caller to do with it.
+     */
+    sendInBackground(to: string, subject: string, text: string, html?: string): void;
+    /** Whether sends are failing right now: degraded by a failed send, not yet cleared by a success. */
+    isDeliveryFailing(): boolean;
+    private reportFailure;
+    private reportSuccess;
+    /**
+     * One notice per window, with a running count (#1916). A failure inside an
+     * open window updates that notice; the first failure after it opens a new
+     * one. The notice is created with `escalate: false`, so it is never emailed:
+     * that send would fail and report another failure.
+     *
+     * Never throws — it runs off the failed send, and a notice that cannot be
+     * written is already covered by the error log above.
+     */
+    private noticeAdministrators;
+    private createNotice;
+    private noticeMessage;
+    private notifications;
     /** Name of the active provider: 'console' | 'smtp' */
     getProviderName(): string;
     /** Effective from address (smtp.from or mail.from) */

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

@@ -1,4 +1,4 @@
-import BaseManager from './BaseManager.js';
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { type ActorContext } from '../context/ActorContext.js';
 import { type VaultPageNotesOutside, type PageRef } from '../utils/pageNotes.js';
@@ -17,6 +17,15 @@ export default class FootnoteManager extends BaseManager {
     private readonly outsideCheck;
     constructor(engine: WikiEngine);
     initialize(): Promise<void>;
+    /**
+     * The public folder is in the backup (#1876), as `<stem>.footnotes.tar` beside
+     * the document: the public pages' footnotes. A vault page's are in its vault, which
+     * PageManager backs up with the vault, sealed as stored.
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /** Staged for the next start with the rest of a site restore (#1876); the live folder is untouched. */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
     isEnabled(): boolean;
     /** The public folder and the vaults, as configured now (#1839). */
     private roots;

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

@@ -25,6 +25,12 @@ export interface NotificationInput {
     level?: 'info' | 'warning' | 'error' | 'success';
     targetUsers?: string[];
     expiresAt?: Date | null;
+    /**
+     * False: never email this notification, whatever the escalation settings
+     * (#1916). A notice that email is failing must not itself be emailed — the
+     * send would fail and report another failure. Not stored.
+     */
+    escalate?: boolean;
 }
 /**
  * Notification statistics
@@ -102,6 +108,13 @@ declare class NotificationManager extends BaseManager {
      * @returns {Promise<string>} Notification ID
      */
     createNotification(notification: NotificationInput): Promise<string>;
+    /**
+     * Replace an active notification's message in place (#1916) — a running
+     * count on one notice instead of a new notice per event. Never escalates:
+     * the notification was already escalated, or not, when it was created.
+     * @returns false when there is no such notification
+     */
+    updateNotificationMessage(notificationId: string, message: string): Promise<boolean>;
     /**
      * Add a notification (alias for createNotification for backward compatibility)
      * @param {NotificationInput} notification - Notification object

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

@@ -1,7 +1,9 @@
-import BaseManager, { type ManagerStats } from './BaseManager.js';
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
-import type { Organization, OrganizationUpdate } from '../types/Organization.js';
+import type { Organization, OrganizationInput, OrganizationUpdate } from '../types/Organization.js';
 import type { OrganizationProvider } from '../types/OrganizationProvider.js';
+import type { Person } from '../types/Person.js';
+import type { ActorContext } from '../context/ActorContext.js';
 /**
  * Subset of install-form data this manager needs to seed the anchor org.
  * Kept narrow so InstallService and tests can pass plain objects without
@@ -34,6 +36,8 @@ declare class OrganizationManager extends BaseManager {
     readonly description = "Canonical Organization records (#617)";
     private provider;
     private providerClass?;
+    /** `ngdpbase.application.organization.storagedir`, resolved at start: what a backup copies (#1876). */
+    private storageDir;
     private installOrgCache;
     private byIdCache;
     private byFileCache;
@@ -41,6 +45,11 @@ declare class OrganizationManager extends BaseManager {
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /** Provider accessor, mainly for tests. */
+    /** Organization records are in the backup (#1876), as `<stem>.organizations.tar` beside the document. */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /** Staged for the next start with the rest of a site restore (#1876); the live records are untouched. */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
     getProvider(): OrganizationProvider | null;
     /**
      * Create the anchor organization from the instance's own identity (#1027).
@@ -81,10 +90,35 @@ declare class OrganizationManager extends BaseManager {
     getByFile(filename: string): Promise<Organization | null>;
     /** #1006: how many organizations this instance holds. Count only. */
     getManagerStats(): Promise<ManagerStats>;
-    list(): Promise<Organization[]>;
-    create(org: Organization, filename?: string): Promise<Organization>;
-    update(id: string, patch: OrganizationUpdate): Promise<Organization | null>;
-    delete(id: string): Promise<boolean>;
+    /** 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`). */
+    get(ctx: ActorContext, id: string): Promise<Organization | null>;
+    /**
+     * Organizations whose `name`, `legalName`, `email` or a contact point's
+     * email contains `query`, ignoring case; an empty query matches all. At
+     * most `limit` (`ngdpbase.application.organization.search.limit` by default).
+     */
+    search(ctx: ActorContext, query: string, options?: {
+        limit?: number;
+    }): Promise<Organization[]>;
+    /**
+     * The people affiliated with an organization, read from each person's
+     * `affiliation` (#1930): the link is stored once, on the person. Each comes
+     * with the role they hold there, when one is given.
+     */
+    people(ctx: ActorContext, organizationId: string): Promise<Array<{
+        person: Person;
+        role?: string;
+    }>>;
+    /**
+     * Create an organization. `name` is required; `@id` defaults to the `url`,
+     * else a new `urn:uuid:`. `filename` is for the install anchor (seeding);
+     * other records take one from the url or name.
+     */
+    create(ctx: ActorContext, org: OrganizationInput, filename?: string): Promise<Organization>;
+    update(ctx: ActorContext, id: string, patch: OrganizationUpdate): Promise<Organization | null>;
+    delete(ctx: ActorContext, id: string): Promise<boolean>;
     /**
      * Clear all caches. Called on every write — the simplest correct
      * invalidation. Per-key invalidation can come later if needed.

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

@@ -1,12 +1,37 @@
-import BaseManager, { type ManagerStats } from './BaseManager.js';
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
-import type { Person, PersonUpdate } from '../types/Person.js';
+import type { Person, PersonInput, PersonUpdate } from '../types/Person.js';
 import type { PersonProvider } from '../types/PersonProvider.js';
+import { type ActorContext } from '../context/ActorContext.js';
+/** What the confirmation page shows: the person the link would join. */
+export interface LinkOfferDetails {
+    personName: string | null;
+    email: string;
+}
+/** The outcome of offering a sign-up link (#1930). */
+export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' | 'failed';
 /**
- * PersonManager — canonical core record for persons (#617).
+ * PersonManager — canonical core record for persons (#617), and the door for
+ * contacts (#1930).
+ *
+ * A person may have an account or not. Each account has exactly one person
+ * (`identifier` = the username); a person with no account has the identifier
+ * `person:<uuid>`, which no username may take. UserManager calls the door on
+ * the account lifecycle under a system context.
+ *
+ * The door: `create`, `update`, `delete`, `get`, `list`, `search` and
+ * `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).
+ *
+ * A later sign-up joins a person with no account in one of two ways: the new
+ * account confirms an emailed link (`offerSignUpLink` → `confirmSignUpLink`),
+ * or an administrator links them (`linkAccount`). Either way the existing
+ * 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.
  *
- * Each User has at most one paired Person record. UserManager calls
- * `create`/`update`/`delete` here on the matching user lifecycle events.
  * `getByUserIdentifier(username)` remains as a lazy-migration entry point
  * for legacy users that pre-date the sync wiring.
  */
@@ -14,20 +39,91 @@ declare class PersonManager extends BaseManager {
     readonly description = "Canonical Person records (#617)";
     private provider;
     private providerClass?;
+    /** `ngdpbase.application.persons.storagedir`, resolved at start: what a backup copies (#1876). */
+    private storageDir;
     private byIdentifierCache;
     private byIdCache;
     private metricsRef;
+    /** Sign-up link offers by token (#1930). In memory: a restart drops them, and an administrator links by hand. */
+    private linkOffers;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
+    /** Person records are in the backup (#1876), as `<stem>.persons.tar` beside the document. */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /** Staged for the next start with the rest of a site restore (#1876); the live records are untouched. */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
     getProvider(): PersonProvider | null;
     getById(id: string): Promise<Person | null>;
     getByIdentifier(identifier: string): Promise<Person | null>;
     /** #1006: how many people this instance holds. Count only, never records. */
     getManagerStats(): Promise<ManagerStats>;
-    list(): Promise<Person[]>;
-    create(person: Person): Promise<Person>;
-    update(id: string, patch: PersonUpdate): Promise<Person | null>;
-    delete(id: string): Promise<boolean>;
+    /** 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`). */
+    get(ctx: ActorContext, id: string): Promise<Person | null>;
+    /**
+     * Persons whose name (`name`, `givenName`, `familyName`) or `email` contains
+     * `query`, ignoring case; an empty query matches everyone. `accountless`
+     * narrows to persons with no account. At most `limit` results
+     * (`ngdpbase.application.persons.search.limit` by default).
+     */
+    search(ctx: ActorContext, query: string, options?: {
+        limit?: number;
+        accountless?: boolean;
+    }): Promise<Person[]>;
+    /**
+     * Create a person. With no `identifier` the person has no account and gets
+     * `person:<uuid>`. An `identifier` must be an existing account that has no
+     * 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. */
+    update(ctx: ActorContext, id: string, patch: PersonUpdate): Promise<Person | null>;
+    delete(ctx: ActorContext, id: string): Promise<boolean>;
+    /**
+     * An administrator joins a person who has no account to an account (#1930),
+     * for when the email differs or none was given. Asks `contact-manage` and
+     * `user-edit`. The person keeps its `@id`; the account's own person, if it
+     * has one, is folded in and removed.
+     */
+    linkAccount(ctx: ActorContext, personId: string, username: string): Promise<Person>;
+    /**
+     * Offer a new account the person with no account who has the same email
+     * ("Is this you?"): a single-use link is mailed to that address, and the
+     * account joins the person only when it confirms. Called by UserManager
+     * after an account is created. Skipped when email links are not available
+     * on this site; nothing is offered when no person, or more than one, has
+     * that address (an administrator links those by hand). `ctx` is the context
+     * the account was created under, named in the log.
+     */
+    offerSignUpLink(ctx: ActorContext, username: string): Promise<LinkOfferOutcome>;
+    /** What the confirmation page shows, for the signed-in account the link was sent to; null for an unknown, used, expired or other account's link. */
+    signUpLinkOffer(ctx: ActorContext, token: string): Promise<LinkOfferDetails | null>;
+    /**
+     * The new account confirms the emailed link: it is joined to the person.
+     * Single use. The link is the authority — it proves the address and is
+     * bound to the account it was sent for — so no permission is asked; the
+     * change is recorded under the account's own context. Null for a link that
+     * is unknown, used, expired, or another account's.
+     */
+    confirmSignUpLink(ctx: ActorContext, token: string): Promise<Person | null>;
+    /** The new account says the record is not theirs: the link is dropped. */
+    declineSignUpLink(ctx: ActorContext, token: string): boolean;
+    private liveOffer;
+    private sweepLinkOffers;
+    /**
+     * Join `username` to the person `personId`, who has no account. The person
+     * takes the account's identifier and keeps its `@id`; fields it lacks are
+     * filled from the account's own person, that person's role memberships move
+     * 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. */
+    private checkedAffiliations;
+    private configNumber;
     /**
      * Clear all caches. Called on every write — the simplest correct
      * invalidation. Per-key invalidation can come later if needed.
@@ -45,4 +141,5 @@ declare class PersonManager extends BaseManager {
     private getMetrics;
     private normalizeProviderName;
 }
+export { ContactRefusedError } from '../utils/contactAccess.js';
 export default PersonManager;

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

@@ -1,4 +1,4 @@
-import BaseManager from './BaseManager.js';
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { Role, RoleUpdate } from '../types/Role.js';
 import type { RoleProvider } from '../types/RoleProvider.js';
@@ -8,6 +8,8 @@ declare class RoleManager extends BaseManager {
     readonly description = "Canonical OrganizationRole records (#617 follow-up)";
     private provider;
     private providerClass?;
+    /** `ngdpbase.application.roles.storagedir`, resolved at start: what a backup copies (#1876). */
+    private storageDir;
     private memberCache;
     private byOrgPositionCache;
     private metricsRef;
@@ -31,6 +33,15 @@ declare class RoleManager extends BaseManager {
      * as is any other `additionalProperty` entry.
      */
     private stripCatalogueCopies;
+    /**
+     * Role membership is in the backup (#1876): the role records folder, as
+     * `<stem>.roles.tar` beside the document. Without it restored users would
+     * have no roles.
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /** Staged for the next start with the rest of a site restore (#1876); the live records are untouched. */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
     /** Provider accessor, mainly for tests. */
     getProvider(): RoleProvider | null;
     getById(id: string): Promise<Role | null>;
@@ -102,6 +113,13 @@ declare class RoleManager extends BaseManager {
      * @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.
+     */
+    moveMemberships(fromPersonId: string, toPersonId: string): Promise<number>;
     /** Remove a deleted account's Person from every role it held. */
     removeAllMemberships(username: string): Promise<void>;
     /**

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

@@ -461,6 +461,14 @@ declare class UserManager extends BaseManager {
         limit?: number;
         activeOnly?: boolean;
     }, ctx: ActorContext): Promise<Omit<User, 'password'>[]>;
+    /**
+     * The account lifecycle reaches PersonManager's door under a system context
+     * (#1930): keeping an account's person in step with the account is core's
+     * own bookkeeping, not the caller's contact management, so it never depends
+     * on the caller holding `contact-manage`. The reason names the account and
+     * who changed it, so the record says why.
+     */
+    private personSyncContext;
     /**
      * Persist a Person record paired with a newly-created User. The install's
      * anchor org (when configured) is referenced via `memberOf`; without it
@@ -468,6 +476,13 @@ declare class UserManager extends BaseManager {
      * thrown — auth must still succeed if Person storage is degraded.
      */
     private syncPersonOnCreate;
+    /**
+     * At sign-up, offer the new account a person with no account who has the
+     * same email (#1930): PersonManager mails an "Is this you?" link, and joins
+     * them only when the account confirms. Skipped when email is off. Never
+     * fails the account write.
+     */
+    private offerContactLink;
     private syncPersonOnUpdate;
     private syncPersonOnDelete;
     createSession(username: string, additionalData?: Record<string, unknown>): Promise<string>;

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

@@ -3,6 +3,8 @@ import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { ProviderInfo } from './BasePageProvider.js';
 import BaseProvider from './BaseProvider.js';
+import type { AttachmentFilesBackupData, AttachmentFilesBackupOutcome } from './attachmentFilesBackup.js';
+import type { PartOutcome } from '../utils/siteRestore.js';
 /**
  * File information for attachment uploads
  */
@@ -187,6 +189,18 @@ declare abstract class BaseAttachmentProvider extends BaseProvider implements At
      * @returns {Promise<void>}
      */
     abstract restore(backupData: Record<string, unknown>): Promise<void>;
+    /**
+     * Write the attachment files themselves beside the backup document (#1876),
+     * streamed, bytes as stored. A provider without it can't be backed up whole,
+     * and AttachmentManager's backup says so.
+     */
+    backupFiles?(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+    /** Stage the files and metadata from a backup for the next start, as part of a site restore (#1876). */
+    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+        skippedVaults: string[];
+    }>;
+    /** What the start did with a staged restore of the files (#1876), once; null when there was none. */
+    takeRestoreAtStart?(): PartOutcome | null;
     /**
      * Shutdown the provider (cleanup resources)
      * @returns {Promise<void>}

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

@@ -5,6 +5,8 @@ import type { AssetProvider, AssetRecord, AssetQuery, AssetPage, AssetInput, Ass
 import type { CreativeWork } from '../types/Schema.js';
 import type { ActorContext } from '../context/ActorContext.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
+import { type PartOutcome } from '../utils/siteRestore.js';
+import { type AttachmentFilesBackupData, type AttachmentFilesBackupOutcome } from './attachmentFilesBackup.js';
 /**
  * Schema.org Person metadata
  */
@@ -122,6 +124,8 @@ export declare function safeStoredExtension(originalName: string, mimeType?: str
  */
 declare class BasicAttachmentProvider extends BaseAttachmentProvider implements AssetProvider {
     private storageDirectory;
+    /** What the start did with a staged restore of the files (#1876). */
+    private restoreAtStart;
     /** Pre-#1386 attachments/{legacyprivateroot}/{user}/ — migrate-FROM and read fallback only. */
     private legacyPrivateDir;
     private pagesDirectory;
@@ -149,8 +153,15 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
     /**
      * Initialize the provider
      * All configuration access via ConfigurationManager
+     *
+     * @param options.readOnly - Open for reading only (#1852): load the index and
+     *   change nothing on disk. No staged restore is applied, no folder is
+     *   created, and neither start-up migration (legacy private files, stale
+     *   paths) runs. For an operator report such as the files dry run.
      */
-    initialize(): Promise<void>;
+    initialize(options?: {
+        readOnly?: boolean;
+    }): Promise<void>;
     /**
      * Verify that the attachment storage directory is accessible.
      *
@@ -210,7 +221,7 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
      * @param fileBuffer - File data
      * @param fileInfo - { originalName, mimeType, size }
      * @param metadata - Schema.org CreativeWork metadata
-     * @param user - User object { name, email }
+     * @param user - The uploader: `username` is recorded as author and editor (#1926)
      * @param options - Privacy-aware storage options
      * @returns Complete attachment metadata
      * @private
@@ -435,6 +446,19 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
      * @returns Backup data
      */
     backup(): Promise<BackupData>;
+    /** Where the attachment files are, for their backup and staged restore (#1876). */
+    private filePlaces;
+    /** The files themselves, beside the backup document (#1876): the shared pool and every vault's, as stored. */
+    backupFiles(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+    /**
+     * Stage the files and the shared metadata from a backup for the next start
+     * (#1876). The metadata is the document's; the live files and metadata are
+     * not touched.
+     */
+    stageFilesRestore(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+        skippedVaults: string[];
+    }>;
+    takeRestoreAtStart(): PartOutcome | null;
     /**
      * Restore provider data from backup
      * @param backupData - Backup data

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

@@ -36,6 +36,13 @@ declare class SqliteDatabaseProvider extends BaseDatabaseProvider<SqliteHandle>
         busyTimeoutMs?: number;
     });
     private static unlock;
+    /**
+     * Read a database file once, read-only, under `key`, and close it (#1876):
+     * nothing is migrated or written. Used for the copy a restore kept as
+     * `*.pre-restore`, to read what the site had recorded just before the
+     * restore replaced it.
+     */
+    static readOnce<T>(file: string, key: string, read: (db: SqliteHandle) => T): T;
     /** Read an existing file read-only: the key opens it and it passes the quick check, or this throws. */
     private static probe;
     /**

package/lib/src/providers/SqliteDatabaseProvider.js

@@ -62,6 +62,22 @@ class SqliteDatabaseProvider extends BaseDatabaseProvider {
         db.pragma("cipher='sqlcipher'");
         db.pragma(`key='${key.replace(/'/g, "''")}'`);
     }
+    /**
+     * Read a database file once, read-only, under `key`, and close it (#1876):
+     * nothing is migrated or written. Used for the copy a restore kept as
+     * `*.pre-restore`, to read what the site had recorded just before the
+     * restore replaced it.
+     */
+    static readOnce(file, key, read) {
+        const db = new Database(file, { readonly: true, fileMustExist: true });
+        try {
+            SqliteDatabaseProvider.unlock(db, key);
+            return read(db);
+        }
+        finally {
+            db.close();
+        }
+    }
     /** Read an existing file read-only: the key opens it and it passes the quick check, or this throws. */
     static probe(file, key) {
         const db = new Database(file, { readonly: true, fileMustExist: true });

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

@@ -39,3 +39,13 @@ declare class SqliteJobStateProvider implements JobStateProvider {
     releaseLock(jobId: string, slot: string, owner: string): Promise<void>;
 }
 export default SqliteJobStateProvider;
+/**
+ * Every job's runs started after `since`, from a database handle (#1876): the
+ * application database a restore kept as `*.pre-restore`, read just after it
+ * was replaced, so the restore's notice names the runs the restored job
+ * history no longer has. The same table `listRuns` reads.
+ */
+export declare function runsStartedAfter(db: Handle, since: string): Array<{
+    jobId: string;
+    run: JobRunRecord;
+}>;

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

@@ -0,0 +1,52 @@
+import { type PartOutcome } from '../utils/siteRestore.js';
+import { type PrivateStoreLayout } from '../utils/privateStorePath.js';
+/** Where the attachment files live on this site. */
+export interface AttachmentFilePlaces {
+    /** The shared pool folder. */
+    pool: string;
+    /** The shared pool's metadata file (inside the pool by default). */
+    metadataFile: string;
+    /** The pages folder, which holds the vaults. */
+    pagesDirectory: string | null;
+    layout: PrivateStoreLayout;
+}
+/** The files part of AttachmentManager's entry in the backup document. */
+export interface AttachmentFilesBackupData {
+    format: 1;
+    pool: {
+        archive: string;
+        files: number;
+        bytes: number;
+    };
+    vaults: {
+        archive: string;
+        files: number;
+        bytes: number;
+        stores: string[];
+    };
+    /** `backupKeyFingerprint()` of the key both archives are encrypted under; absent when they are not. */
+    keyFingerprint?: string;
+}
+export interface AttachmentFilesBackupOutcome {
+    data: AttachmentFilesBackupData;
+    /** Parts left out (a symbolic link, a vault folder whose name can't be a path segment), each named. */
+    warnings: string[];
+}
+/** Write the attachment files beside the backup document: the pool, then every vault's. Never base64, never whole in memory. */
+export declare function backupAttachmentFiles(places: AttachmentFilePlaces, directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+/**
+ * Stage the attachment files from a backup for the next start, and record
+ * the part in the site restore. All or nothing: on any failure every staged
+ * path is removed and nothing is recorded.
+ *
+ * @returns the vaults the backup holds that this site doesn't have (not staged).
+ */
+export declare function stageAttachmentFiles(places: AttachmentFilePlaces, directory: string, data: AttachmentFilesBackupData, metadataJson: string, siteRestore: string): Promise<{
+    skippedVaults: string[];
+}>;
+/**
+ * Put staged attachment files in place, at start, before the metadata is
+ * read: only the pool, its metadata file and vault attachment paths may be
+ * replaced, whatever the manifest says.
+ */
+export declare function applyAttachmentFilesAtStart(places: AttachmentFilePlaces, siteRestore: string): PartOutcome | null;

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

@@ -126,3 +126,9 @@ export interface ApplyOutcome {
  * be replaced, so a tampered manifest cannot rename an arbitrary file.
  */
 export declare function applyStagedRestore(applicationFile: string, allowed: (live: string) => boolean): ApplyOutcome | null;
+/**
+ * Set a staged restore aside without applying any of it (#1876): every
+ * `*.db.staged` beside the application database and the manifest become
+ * `*.incomplete`. Used when the site restore it belongs to is not applied.
+ */
+export declare function setAsideStagedRestore(applicationFile: string, reason: string): ApplyOutcome;