@jwilleke/ngdpbase-types 5.40.0 → 5.41.1

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

@@ -0,0 +1,182 @@
+/**
+ * FileManager — the one door for files (#1852, epic #1851).
+ *
+ * It reads today's attachments as file records (src/types/File.ts): the
+ * shared pool as the public place, and every vault the requester may read.
+ * It writes through one door, `put` (#2148): a file goes into the place the
+ * caller chose, after the permission for that place, with AttachmentManager
+ * as the storage underneath; `placesWritableBy` lists the places a user may
+ * write to. Rename, move, delete and per-place indexes are later steps
+ * (docs/guides/storage-developer-guide.md).
+ *
+ * Read access is the existing rules, asked at this door:
+ * - the public place needs `asset-read`, from the PDP;
+ * - a vault is read through AttachmentManager's own vault reads, so the
+ *   container rule (owner or delegate, never a role, admin included) decides
+ *   exactly as it does for a vault page's files.
+ *
+ * The operator inventory (the migration dry run, #1859) is not on the
+ * engine's door: only an instance opened by {@link FileManager.openForOperator},
+ * from the command line, answers it.
+ */
+import BaseManager from './BaseManager.js';
+import { type AttachmentMetadata, type PutFile, type PutOptions, type UploadOptions } from './AttachmentManager.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { type AttachmentDetail } from '../utils/auditEvents.js';
+import { type AssetRecord } from '../types/Asset.js';
+import type { FileInventory, FilePlace, FileRecord } from '../types/File.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import { type FileMigrationReport } from '../utils/fileMigrationPlan.js';
+/**
+ * What `put` hands back (#2149): the stored file's metadata, and, when
+ * vetting cleaned it, what was removed (one note per kind), so the uploader
+ * can be told.
+ */
+export type PutResult = AttachmentMetadata & {
+    cleaned?: string[];
+};
+/** A place the Upload file dialog offers (#2149): its key in the form, the words the user reads, and the place. */
+export interface UploadPlace {
+    key: string;
+    label: string;
+    place: FilePlace;
+}
+/** Where the Upload file dialog was opened (#2149): the page's path, and the page it shows, when there is one. */
+export interface UploadWhere {
+    path?: string;
+    pageName?: string;
+}
+declare class FileManager extends BaseManager {
+    /** Set only by {@link openForOperator}: this instance answers the inventory. */
+    private operatorInstance;
+    constructor(engine: WikiEngine);
+    /**
+     * Open the door read-only for an operator command (#1859): the site's
+     * configuration and attachment index, with nothing else started and
+     * nothing written. The site may be running; this process changes no file.
+     */
+    static openForOperator(): Promise<FileManager>;
+    /** Every file `ctx` may read, newest first; `place` narrows it to one place. */
+    list(ctx: ActorContext, filter?: {
+        place?: FilePlace;
+    }): Promise<FileRecord[]>;
+    /** The file with this id, when `ctx` may read it. */
+    get(id: string, ctx: ActorContext): Promise<FileRecord | null>;
+    /**
+     * The files named `filename` that `ctx` may read: one per place at most,
+     * since a name is unique within a place (today's pool can hold more than
+     * one, which is what the migration's suffixes are for). `place` narrows it.
+     */
+    findByName(filename: string, ctx: ActorContext, place?: FilePlace): Promise<FileRecord[]>;
+    /**
+     * The username a public record's uploader names (#2097): the uploader is
+     * stored as an identity @id, resolved through IdentityManager; an orphan,
+     * an @id with no account, `Unknown` or an email names no owner.
+     */
+    private ownerOf;
+    private readable;
+    /** `asset-read` for the public place, from the PDP. No PDP, no answer: closed. */
+    private mayReadPublic;
+    /**
+     * The places `ctx` may put a file in (#2148, operator 2026-10-30): the
+     * public place when the PDP grants `asset-upload`; each of the user's own
+     * vaults the vault rule lets them upload to (the default vault, and every
+     * vault they already have); each shared folder where they hold
+     * `shared-folder-file`. A place they may not write to is never listed.
+     *
+     * Each place is asked exactly as {@link put} asks it, so what is offered is
+     * what the door allows. An affordance: nothing is recorded.
+     */
+    placesWritableBy(ctx: ActorContext): Promise<FilePlace[]>;
+    /**
+     * Put a file in `place` (#2148): the one write door. The permission for
+     * that place is asked first, and a refusal stores nothing. Then ICE vets
+     * the file (#2149): its type from its bytes, and its format's shim cleans
+     * it; the cleaned copy is the one kept. AttachmentManager stores it as the
+     * place requires (sealed in a sealed vault or shared folder), and this door
+     * records the upload with what vetting removed (a sealed place's file by
+     * id only, #2048). No page decides the place: `options.pageName` is only
+     * the page that shows it.
+     *
+     * @throws Error 'Permission denied: …' when `ctx` may not write there, or
+     *   is nobody (#1926); a route answers it 401 or 403.
+     * @throws IceVetRefused when the file could not be checked; nothing is stored
+     */
+    put(ctx: ActorContext, place: FilePlace, file: PutFile, options?: PutOptions): Promise<PutResult>;
+    /**
+     * Record a file stored or deleted (#2149: moved here from AttachmentManager,
+     * which stores and records nothing itself). An upload is `continue`: a
+     * failed record is logged, never fatal. A delete is critical: it rethrows,
+     * tagged `AUDIT_WRITE_FAILED`, so the delete does not happen unrecorded and
+     * a caller can tell an unwritable record from a failed delete.
+     *
+     * A sealed store's file is recorded by id and store only (#2048), its
+     * owner by identity @id with the username beside it (#2041).
+     * AttachmentManager's delete door calls this until deleting is FileManager's.
+     */
+    recordFileEvent(op: 'upload' | 'delete', context: ActorContext, detail: AttachmentDetail, wikiContext?: {
+        request?: {
+            ip?: string;
+        } | null;
+    }): Promise<void>;
+    /**
+     * What the Upload file dialog offers `ctx` (#2149): every place
+     * {@link placesWritableBy} lists, and nothing else, each with the words the
+     * user reads; and the one selected at first: where they are working
+     * ({@link workingPlaceKey}), else the public place, else the first. Never
+     * inferred from whether a page exists. An affordance: nothing is recorded.
+     */
+    uploadPlaces(ctx: ActorContext, where?: UploadWhere): Promise<{
+        places: UploadPlace[];
+        defaultKey: string | null;
+    }>;
+    /** The place a dialog key names, when it is one `ctx` may write to (#2149); null otherwise. Never a place it was not offered. */
+    placeForKey(ctx: ActorContext, key: string): Promise<FilePlace | null>;
+    /** A place's key in the dialog: `public`, `vault:<id>` (always the user's own) or `folder:<name>`. */
+    static placeKey(place: FilePlace): string;
+    /** The words the user reads for a place. */
+    private placeLabel;
+    /**
+     * Where the user is working, as a dialog key (#2149): a shared folder's
+     * list (`/shared/<folder>`) or one of its pages is that folder; a page in
+     * one of their own vaults is that vault. Read from the location, never
+     * from whether a page by that name exists; anywhere else is no place.
+     */
+    private workingPlaceKey;
+    /**
+     * The place today's page-tied upload goes to (#1396, #1398, #2125), until
+     * #2149/#2150 move its callers to a place the user chose: an upload onto a
+     * shared folder's page goes into that folder, saved or not; onto a vault
+     * page into that page's vault, by someone who may edit the page; with the
+     * Private tick into the uploader's own vault (`store`, or their default);
+     * otherwise the public place.
+     */
+    placeForPageUpload(ctx: ActorContext, options: Pick<UploadOptions, 'pageName' | 'private' | 'store'>): Promise<FilePlace>;
+    /** May `ctx` put a file in `place`? The existing rule for each kind, asked of its owner. */
+    private mayPut;
+    /** The user's own vaults a file may go in: their default vault, and every vault they already have. */
+    private ownVaultIds;
+    private storeLayout;
+    /** A well-formed place: a vault is a user's (never the shared folders' container), with valid ids. */
+    private static isPlace;
+    /** A place in a log line. Ids only, never a file's name. */
+    private static describePlace;
+    /**
+     * Everything kept as files, for the migration dry run: the public files in
+     * full and each vault as counts (files, bytes, clash renames), never its
+     * names. Only on an instance opened by {@link openForOperator}, for an
+     * operator's context.
+     */
+    inventory(ctx: ActorContext): Promise<FileInventory>;
+    /** The dry run: the inventory, planned with the configured values. Writes nothing. */
+    migrationDryRun(ctx: ActorContext): Promise<FileMigrationReport>;
+    /** An asset record as a file record: the same fields, plus place, owner and system-category. */
+    static toFileRecord(asset: AssetRecord, place: FilePlace, owner: string | null, systemCategory: string | null): FileRecord;
+    private configManager;
+    /** The public place's category today: the default entry of `ngdpbase.system-category`. */
+    private defaultCategory;
+    /** The category that declares this vault, or null when none does. */
+    private vaultCategory;
+    private suffixDigits;
+}
+export default FileManager;

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

@@ -33,7 +33,7 @@ import { IContentConverter } from '../converters/IContentConverter.js';
 import { type ZipReadLimits } from '../utils/zipArchive.js';
 import { type JobContext } from '../context/JobContext.js';
 import { type IceNameForm } from '../ice/givenName.js';
-import type { IceLedger, IceOriginalChoices, IceReceiver, IceRunReport, IceRunRequest, IceShim, RecentImport, RegisteredShim } from '../ice/types.js';
+import type { IceExportFormat, IceExportReport, IceExportRequest, IceExportSource, IceLedger, IceOriginalChoices, IceReceiver, IceRunReport, IceRunRequest, IceShim, IceTarget, IceUpload, IceVetResult, RecentImport, RegisteredShim } from '../ice/types.js';
 /**
  * Options for import operations
  */
@@ -218,6 +218,31 @@ export declare class ImportUploadRefused extends Error {
     readonly reason: string;
     constructor(file: string, reason: string);
 }
+/**
+ * An export that is not started (#2120): the thing is not there, the user may
+ * not export it, or the format is not one offered for it. A route answers it
+ * as "not found", so it never tells the user which.
+ */
+export declare class IceExportRefused extends Error {
+    constructor(message?: string);
+}
+/**
+ * An export not started because too much is already being made (#2120): the
+ * user's own queued exports are at `max-queued-per-user`, or every held run is
+ * still being made. A route answers it as 429; nothing was read or queued.
+ */
+export declare class IceExportBusy extends Error {
+    constructor(message: string);
+}
+/**
+ * An export refused only because the user's sign-in is not fresh enough
+ * (#2120): they hold `permission` on the thing, and step-up asks for it. A
+ * route answers it with the step-up prompt, not "not found".
+ */
+export declare class IceExportNeedsFreshSignIn extends Error {
+    readonly permission: string;
+    constructor(permission: string);
+}
 /** One page's outcome in a takeout import (#1472). */
 export type TakeoutPageOutcome = {
     title: string;
@@ -272,13 +297,11 @@ export interface UsableReceiver {
     originals: Required<Omit<IceOriginalChoices, 'types'>>;
     /** What a name the user gives becomes (#2130), when the receiver takes one: the screen offers the field only then. */
     names?: IceNameForm;
+    /** Where within it this user may import (#2118), for a receiver with places: the screen offers a choice of them. */
+    targets?: IceTarget[];
 }
-/**
- * Import Manager class
- *
- * Manages content import with extensible format support via converter registry.
- */
 declare class ImportManager extends BaseManager {
+    #private;
     /** Registry of format converters */
     private converterRegistry;
     /** ICE (#1979): shims by id (`<owner>.<name>`), in registration order. */
@@ -287,13 +310,19 @@ declare class ImportManager extends BaseManager {
     private readonly receiverRegistry;
     /** ICE: runs this process knows about, oldest first. */
     private readonly iceRuns;
-    /** ICE: runs waiting for the background job, each with its own context. */
+    /** ICE (#2171): a rechecking run's store, as fingerprint → id, read once per run and store; dropped when the run ends. */
+    private readonly storeHoldings;
+    /** ICE: work waiting for the background job, each with its own context: an import run or an export (#2120). */
     private readonly iceQueue;
     /** ICE: true while a background job is draining the queue. */
     private iceDraining;
     /** ICE: the last background run id the queue was handed to. */
     private iceLastJobRunId;
     private iceLedger;
+    /** ICE export (#2120): the owners' doors for reading what is exported, by id. */
+    private readonly exportSourceRegistry;
+    /** ICE export: runs this process holds, oldest first, each with its file once made. Never written to disk. */
+    private readonly exportRuns;
     constructor(engine: WikiEngine);
     /**
      * Initialize the manager
@@ -319,7 +348,9 @@ declare class ImportManager extends BaseManager {
     /**
      * Register a receiver (D4): a door that already exists. Core's are
      * `core.pages` and `core.files`; an add-on registers its own manager's door
-     * through `host.registerReceiver`.
+     * through `host.registerReceiver`. Refuses `writesEncrypted` from every
+     * caller, whatever owner it names: core registers its own receivers
+     * through the private `#registerReceiver` (#2179).
      *
      * @returns The receiver's id, `<owner>.<name>`
      */
@@ -350,12 +381,35 @@ declare class ImportManager extends BaseManager {
      * `ngdpbase.import.engine.default-original` when allowed, else the first.
      */
     private originalChoices;
+    /**
+     * The request's place within the receiver, checked (#2118): one the
+     * receiver's `targets` gives this context, for a receiver with places,
+     * and none for any other. An unknown receiver is left for the run to report.
+     *
+     * @throws Error when the place is missing, not this user's, or not the receiver's
+     */
+    private checkTarget;
     /**
      * The request as the engine runs it: the receiver's default original when
      * none was chosen, and a refusal for a choice the receiver does not offer
      * (D11, #2021). An unknown receiver is left for the run to report.
      */
     private withOriginal;
+    /**
+     * Vet one file before it is kept as a file (#2149): its type from its
+     * bytes (#1624), then its format's shim, when that shim is switched on,
+     * cleans it. FileManager asks this for every file it stores, and keeps the
+     * bytes returned, never the ones it sent; `removed` says what was taken
+     * out, for the uploader and the upload's record.
+     *
+     * Runs in the caller's request: cleaning is one linear pass over a file no
+     * larger than the site's upload limit. It decides nothing about permission:
+     * the caller has asked that first.
+     *
+     * @param ctx - Who is keeping the file (P1); only named in the log line when something was cleaned
+     * @throws IceVetRefused when the cleaning shim fails: the file could not be checked, so it is not kept
+     */
+    vetFile(upload: IceUpload, ctx: ActorContext): Promise<IceVetResult>;
     /**
      * Run one import now and wait for it. For code already off the request
      * path: an add-on's own background job, a test. A route uses
@@ -383,6 +437,11 @@ declare class ImportManager extends BaseManager {
      * the store's sealed index entry written. Each is recorded in the ledger
      * as the keep-once record (#2011), so the run reuses it and needs no key.
      *
+     * A receiver whose `receive` itself may write into an encrypted store
+     * (`writesEncrypted`, #2118) has the whole run now, in this request, with
+     * `ctx` and its key, and the run's id is returned when it has ended: no
+     * key is ever carried into a job (#2034).
+     *
      * @throws ImportUploadRefused when an original could not be kept; nothing is queued
      */
     enqueueUpload(request: IceRunRequest, ctx: ActorContext): Promise<string>;
@@ -407,14 +466,105 @@ declare class ImportManager extends BaseManager {
     /**
      * Is an import into this receiver confidential (#2110)? Only when its
      * destination is encrypted: a receiver that keeps into a sealed store
-     * (`keepsEncrypted`). No receiver can declare itself so otherwise. A
+     * (`keepsEncrypted`), or whose own door writes into one
+     * (`writesEncrypted`, #2118). No receiver can declare itself so otherwise. A
      * confidential import's file names are shown to the uploader and kept in
-     * the audit log, and never written to application logs, notices or admin
-     * screens; every other import logs them as before.
+     * the audit log, and never written to application logs, notices, admin
+     * screens or the import ledger (#2161); every other import logs them as before.
      */
     isConfidential(receiverId: string): boolean;
     /** Use this ledger instead of the file one: a test's, or a database table's. */
     setImportLedger(ledger: IceLedger): void;
+    /**
+     * Register an export source (#2120): the owner's door for reading what is
+     * exported, checking its existing read permission (D5). Core's is
+     * `core.pages`.
+     *
+     * @returns The source's id, `<owner>.<name>`
+     * @throws Error when the source is malformed or its id is taken
+     */
+    registerExportSource(owner: string, source: IceExportSource): string;
+    /**
+     * The formats the Export action offers this context for one thing (#2120):
+     * none when the source's owner would not let it export the thing (asked
+     * as an affordance, recording nothing), else each `out` shim, switched on,
+     * that can make a file from what the source yields.
+     */
+    exportFormatsFor(sourceId: string, ref: string, ctx: ActorContext): Promise<IceExportFormat[]>;
+    /**
+     * Start an export (#2120), from the request that asked: the source reads
+     * the thing now, with the request's own context, so its owner's door
+     * decides with everything the request carries (step-up, a vault's key)
+     * and records the export. The shims run off the request path, in the ICE
+     * background job, as the user's own job context. Returns the run id at once.
+     *
+     * Before anything is read, the user may have at most
+     * `max-queued-per-user` exports queued or running, and a held run must be
+     * free to make room under `max-kept-runs`. Once read, the items count
+     * toward `max-held-bytes` until their file is made.
+     *
+     * @throws IceExportRefused when the thing is not there, the user may not
+     *   export it, or the format is not one offered for it
+     * @throws IceExportNeedsFreshSignIn when the user holds the permission but
+     *   step-up asks for a fresh sign-in
+     * @throws IceExportBusy when the user, or the site, is making as many
+     *   exports as it may
+     * @throws IceExportFailed when the thing is larger than this site exports
+     */
+    startExport(request: IceExportRequest, ctx: ActorContext): Promise<string>;
+    /** An export's status, to the user it runs as; null to anyone else, and once it is let go. */
+    getExportRun(runId: string, ctx: ActorContext): IceExportReport | null;
+    /** An export's file, to the user it runs as, while it is kept; null otherwise. */
+    exportFile(runId: string, ctx: ActorContext): {
+        name: string;
+        mediaType: string;
+        bytes: Buffer;
+    } | null;
+    /** The source's formats now: the enabled out shims' chains from what it yields. */
+    private exportChainsFor;
+    private executeExport;
+    /** The source's own record of how an export ended, if it keeps one; a record that fails is logged, never thrown. */
+    private recordExportOutcome;
+    /**
+     * Before a new export is read (#2120): refuse when the user already has
+     * `max-queued-per-user` exports queued or running, and let finished runs go
+     * until there is room under `max-kept-runs`. A queued or running run is
+     * never let go.
+     *
+     * @throws IceExportBusy when there is no room
+     */
+    private makeRoomForExport;
+    /**
+     * Hold a new run with the bytes its items take until its file is made,
+     * which count toward `max-held-bytes` (#2120). Finished files are let go
+     * to make room, the user's own first ({@link finishedExportRuns}).
+     *
+     * @throws IceExportFailed when the items alone are more than it may hold
+     * @throws IceExportBusy when queued and running exports alone hold too much
+     */
+    private holdExportRun;
+    /**
+     * Keep a made file in memory until `keep-minutes` have passed, never on
+     * disk: an export of a sealed vault's page must not rest unencrypted. Its
+     * items' bytes are released for the file's. Other finished files are let
+     * go when all would hold more than `ngdpbase.export.engine.max-held-bytes`,
+     * the user's own first.
+     */
+    private keepExportFile;
+    /** Let finished files go, `username`'s own first, until all held bytes are at most `limit`. */
+    private letFilesGo;
+    /** Every byte exports hold: made files, and the items of runs not yet made. */
+    private heldExportBytes;
+    /**
+     * The runs that may be let go, in the order they are: done or failed only,
+     * `username`'s own oldest first, then everyone else's oldest first, so one
+     * user's exports push out their own before anyone else's (#2120).
+     */
+    private finishedExportRuns;
+    private dropExportRun;
+    /** `ngdpbase.export.engine.*`: every limit an export applies is configuration (the chain's length is import's). */
+    private exportSettings;
+    private exportManager;
     /**
      * The ledger scope a run uses (#2013): bound to the receiver and to the user
      * `ctx` names, by their identity `@id`; their username only when the
@@ -441,7 +591,7 @@ declare class ImportManager extends BaseManager {
     private enabledShims;
     /**
      * Hand the queue to the background job. One job run drains every queued
-     * import, each under its own context. A job run that has finished draining
+     * import and export, each under its own context. A job run that has finished draining
      * but is not yet marked done answers `enqueue` with its old run id; then
      * try again shortly, so nothing queued is stranded.
      */
@@ -471,14 +621,96 @@ declare class ImportManager extends BaseManager {
      */
     private pagesReceiver;
     /**
-     * `core.files` (D4): a file through AttachmentManager's upload door, which
-     * checks `asset-upload` itself. Also where a kept original goes (D11) when
-     * the chosen receiver does not keep its own. It becomes FileManager's write
-     * door once the files layer has one (#1851). A name the user gave (#2130)
+     * `page-export` for this page (#2120). For a page in a vault, asked about
+     * the page as the route door asks it (`hasPermissionOn`, #1539): the
+     * container rule, then the capability with the page's vault, so a
+     * site-wide role does not reach in. For any other page, the capability.
+     * An affordance asks whether it is held (no step-up); the door whether it
+     * is permitted, and a refusal to someone who holds it is step-up's.
+     */
+    private mayExportPage;
+    /**
+     * `core.pages` as an export source (#2120, D5: pages export checks
+     * `page-export`). A page is offered for export when its reader may see it
+     * and holds `page-export` (affordances, recording nothing). Reading it
+     * for export asks `page-export` ({@link mayExportPage}), then reads through the page
+     * door (`readPage`), which decides `page-read` on the page and records a
+     * refusal. The export is recorded as `page-export`, with the format and
+     * the run, once the run has ended: a success only when the file was made.
+     */
+    private pagesExportSource;
+    /**
+     * `core.files` (D4): a file into the public place through FileManager's
+     * write door, `put` (#2149), which asks `asset-upload` itself and vets the
+     * file. Also where a kept original goes (D11) when the chosen receiver does
+     * not keep its own. A name the user gave (#2130)
      * is the stored file's name; when the shared pool has a file of that name
      * already, the item is refused, never stored beside or over it.
      */
     private filesReceiver;
+    /**
+     * `core.private-store` (#2118): a takeout (#1387) handed back into one of
+     * its owner's own private stores, read by the shim `core.takeout`. It
+     * replaces the takeout import's own door (#1472). Each page goes through
+     * PageManager's save door and each file through FileManager's write door
+     * (`put`), the doors an edit and an upload use, so a sealed store
+     * encrypts on write with no new crypto.
+     *
+     * - No new permission (D5): the rule the takeout import always had, the
+     *   `account-security` permission and the user's own private container.
+     * - Its places (`targets`) are the user's own stores this context can
+     *   write now: those on disk and the default one, an encrypted one only
+     *   while it is unlocked in this session.
+     * - Its writes may be sealed (`writesEncrypted`): the engine runs an
+     *   upload into it in the request, with the request's key, and an import
+     *   into it is confidential (#2110): no file or page name is logged.
+     * - Importing the same takeout again leaves the store as the first import
+     *   did (operator, 2026-09-25), except that a page or a file deleted since
+     *   comes back (operator, 2026-10-30; #2171). The engine skips a file it
+     *   already took (fingerprints), but a page with a uuid and a file are read
+     *   again (`rechecks`): the uuid check below decides for a page, and for a
+     *   file whether the store still holds its bytes (`ownStoreFingerprints`, read once a run),
+     *   so one still held is `duplicate` and not put again (no second upload
+     *   record). On a first import the file door returns a file the store
+     *   already holds. A page whose uuid the store holds is `duplicate`: unchanged, or
+     *   changed since the download, and then the page here is kept. A uuid
+     *   used elsewhere on the site is `duplicate`, the page named only when
+     *   the user may view it. A title held by a DIFFERENT page lands beside
+     *   it as `Title (imported)`.
+     * - The original is the file itself: none is kept or cited (D11), as for `core.files`.
+     * - The run is recorded as one act, `store-import`, with counts only, and
+     *   kept as a report page in the store, sealed when the store is (operator,
+     *   2026-09-25 and 2026-10-30): see {@link keepRunReport}.
+     */
+    private privateStoreReceiver;
+    /** The takeout import's rule, unchanged (#1472): `account-security`, and only into the user's own container. */
+    private mayImportIntoOwnStore;
+    /** Where the private-store receiver writes, from configuration. */
+    private privateStoreSetup;
+    /**
+     * The user's own stores this context can write now (#2118): each store on
+     * disk and the default one, which a user on a new site has before they
+     * wrote anything; an encrypted one only while unlocked in this session.
+     * Making a store is its own door (#1414): an encrypted one needs keys.
+     */
+    private ownStoresWritable;
+    /**
+     * One page or file of a takeout into the store `info.target` (#2118, as
+     * #1472 did). A file through FileManager's `put`; a page after the files
+     * it links to, its links pointed at their ids here, through PageManager's
+     * save door. Nothing here logs a page's or a file's name (#1461, #2110).
+     */
+    private receiveTakeoutEntry;
+    /** A takeout's page into the store, as #1472 decided: see {@link privateStoreReceiver}. */
+    private saveTakeoutPage;
+    /**
+     * The run as one act (#1472's `store-import`): who, which store, and how
+     * each file went, as counts. Never a page's or a file's name (#1461); each
+     * file's own record is its door's (`asset-upload`, a sealed store's by id).
+     * The counts use the old door's keys, so whatever reads the event reads
+     * one shape.
+     */
+    private recordStoreImport;
     /**
      * Get available format IDs
      *
@@ -671,6 +903,22 @@ declare class ImportManager extends BaseManager {
         /** The uploaded file's name, for the report page. */
         sourceName?: string;
     }): Promise<TakeoutImportReport>;
+    /**
+     * An engine run into `core.private-store` as the takeout report the old
+     * door keeps (code review of #2160, finding 3; operator, 2026-10-30), from
+     * the run's per-file status. Only a run that read a takeout keeps one.
+     * A file the run skipped as already imported is in neither count.
+     *
+     * @returns How many files no page links to
+     */
+    private keepRunReport;
+    /**
+     * A takeout import's report, kept (operator, 2026-09-25): which files no
+     * page now in the store links to, counted in the log, and a page in the
+     * store it is about, sealed exactly when the store is, so it can name what
+     * a log may not. A failure to save it costs the record, never the import.
+     */
+    private keepTakeoutReport;
     /** The import report page's markdown. Private links are `[Title|store/Title]` (#1457). */
     private takeoutReportMarkdown;
     /**

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

@@ -37,6 +37,8 @@ declare class MediaManager extends BaseManager implements CatalogSource {
     readonly currentSchemaVersion = 1;
     /** Active media provider (null when not yet initialized) */
     private _provider;
+    /** Why configured folders were refused for overlapping private storage (#2195). */
+    private overlapReasons;
     /** The configured media folders, for the degraded-state reason (#1167). */
     private mediaFolders;
     /** Return the active media provider for use by AssetManager. */
@@ -105,6 +107,15 @@ declare class MediaManager extends BaseManager implements CatalogSource {
      * what degraded means (#1155) — configured, wanted, not working.
      */
     private recordFolderState;
+    /** Log and notify admins of each folder refused for overlapping private storage (#2195). */
+    private surfaceOverlaps;
+    /**
+     * Why each of `folders` may not be a media folder, empty when all may (#2195).
+     * The configuration screen asks before saving `ngdpbase.media.folders`.
+     */
+    checkFolders(folders: string[]): string[];
+    /** One path per line, then "and N more" when the provider capped the list (#2191). */
+    private formatFileList;
     /**
      * Surface scan/rebuild anomalies to admins via /admin/notifications and the
      * server log (#807). Missing folders, capture-date gaps, and processing