@jwilleke/ngdpbase-types 5.40.0 → 5.41.0

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

@@ -40,7 +40,7 @@ export type { PageAction } from '../../src/utils/pageUrl.js';
 export type { default as ConsentManager, ConsentScopeStatus } from '../../src/managers/ConsentManager.js';
 export type { AddonConsentRegistration, ConsentDocument, ConsentRecord, ConsentRequiredError, ConsentScope, ConsentSeen, ConsentStatus } from '../../src/types/Consent.js';
 export type { default as ImportManager } from '../../src/managers/ImportManager.js';
-export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, OriginalKeep, IceUpload, IceSource, IceUrlSource, IceRunRequest, IceRecordData, FileDoneInfo, IceRunReport, IceFileReport, IceFileStatus, RecentImport } from '../../src/ice/types.js';
+export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, OriginalKeep, IceUpload, IceSource, IceUrlSource, IceRunRequest, IceRecordData, FileDoneInfo, IceTarget, IceArchiveView, IceRunReport, IceFileReport, IceFileStatus, RecentImport } from '../../src/ice/types.js';
 export type { default as UserManager, UserUpdateInput, UserUpdateFn } from '../../src/managers/UserManager.js';
 export type { User, UserPreferences } from '../../src/types/User.js';
 export type { default as AuthManager, InviteOutcome, InvitationView } from '../../src/managers/AuthManager.js';

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

@@ -41,8 +41,13 @@ export declare function isZip(upload: IceUpload): boolean;
  * with the type its request gave it. Limits are per archive (`ZipReadLimits`), so a small
  * archive that expands enormously stops at the budget. An archive that cannot
  * be read is returned in `unreadable`, with why; the rest go on.
+ *
+ * With `innerZipsAsFiles` (#2118), only the uploads themselves are unpacked:
+ * a zip inside one is passed on as a file, like any other member.
  */
-export declare function expandUploads(uploads: readonly IceUpload[], limits: ZipReadLimits, maxDepth: number, depth?: number): {
+export declare function expandUploads(uploads: readonly IceUpload[], limits: ZipReadLimits, maxDepth: number, options?: {
+    innerZipsAsFiles?: boolean;
+}, depth?: number): {
     files: IceUpload[];
     unreadable: Array<{
         name: string;

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

@@ -0,0 +1,41 @@
+import type { ExportShimTools, IceItem, IceKind, RegisteredShim } from './types.js';
+/** Core's page export source: pages, read through PageManager's door. */
+export declare const PAGES_EXPORT_SOURCE = "core.pages";
+/** Configuration an export reads (each a key under `ngdpbase.export.engine.`). */
+export interface IceExportSettings {
+    /** The most bytes an export's source, or any step of its chain, may hold. */
+    maxBytes: number;
+    /** The most shims one export runs through (`ngdpbase.import.engine.max-chain-depth`, shared with import). */
+    maxChainDepth: number;
+}
+/** An export that cannot be made, with the reason a user is shown. */
+export declare class IceExportFailed extends Error {
+    constructor(message: string);
+}
+/**
+ * The formats that can be made from items of this kind: for each `out`
+ * shim that makes a file, the shortest chain of `out` shims that reaches it
+ * from `kind`, at most `maxChainDepth` long. Shims are tried in registration
+ * order, so between two chains of one length the first registered wins.
+ *
+ * @returns The file-making shim's id → the chain, ending with it
+ */
+export declare function exportChains(shims: readonly RegisteredShim[], kind: IceKind, maxChainDepth: number): Map<string, RegisteredShim[]>;
+/** The bytes items hold, their text counted as UTF-8. */
+export declare function exportSize(items: readonly IceItem[]): number;
+/**
+ * Refuse items larger than the export limit.
+ *
+ * @throws IceExportFailed when they are
+ */
+export declare function checkExportSize(items: readonly IceItem[], maxBytes: number): void;
+/**
+ * Run the source's items through the chain, each shim's output the next
+ * one's input, and return the one file the last shim made. What came before
+ * travels with each item while a shim keeps the count: earlier metadata
+ * under later, as an import's chain does.
+ *
+ * @throws IceExportFailed when a step holds more than `maxBytes`, a shim
+ *   makes something other than what it declares, or the end is not one file
+ */
+export declare function runExportChain(items: IceItem[], chain: readonly RegisteredShim[], tools: (shim: RegisteredShim) => ExportShimTools, settings: IceExportSettings): Promise<IceItem>;

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

@@ -41,10 +41,11 @@ export declare const SCOPE_FORM = "ice2";
  * The scope a run's fingerprints, per-file status and item keys live in
  * (#2013): bound to the receiver and to the user the run is for, by their
  * identity `@id` (else their username, #2041). The engine works it out from
- * the caller's context; a request cannot name another user's. A caller's own
- * `sub` (phr's source id) narrows it within that user's scope, never outside.
+ * the caller's context; a request cannot name another user's. What follows
+ * narrows it within that user's scope, never outside: the place within the
+ * receiver (#2118), then a caller's own sub-scope (phr's source id).
  */
-export declare function boundScope(receiverId: string, owner: string, sub?: string): string;
+export declare function boundScope(receiverId: string, owner: string, ...subs: Array<string | undefined>): string;
 /** Does this shim list the receiver, by id or as any receiver (`'*'`, #2109)? */
 export declare function handsTo(shim: Pick<RegisteredShim, 'receivers'>, receiverId: string): boolean;
 export interface ChainLeaf {
@@ -64,9 +65,10 @@ export interface ChainSpec {
 /**
  * Run a shim, then the shims after it (D9), until each item is done. What
  * came before travels with each item: earlier metadata under later, earlier
- * warnings first. Partial notes are collected into `partial`.
+ * warnings first. Partial notes are collected into `partial`; a shim's note
+ * that the file holds nothing to import on its own (#2118) into `skipped`.
  */
-export declare function convertChain(shim: RegisteredShim, input: IceItem, chain: string[], spec: ChainSpec, partial: string[]): Promise<ChainLeaf[]>;
+export declare function convertChain(shim: RegisteredShim, input: IceItem, chain: string[], spec: ChainSpec, partial: string[], skipped?: string[]): Promise<ChainLeaf[]>;
 /**
  * The name the user gave this file (#2130), as the engine applies it: none
  * when the receiver names things itself (it declares no `names`) or the user
@@ -85,6 +87,13 @@ export declare function resolveGivenName(upload: IceUpload, receiver: Registered
 export declare function receiverLink(receiver: RegisteredReceiver, ref: string | undefined, ctx: ActorContext): Promise<string | undefined>;
 /** What a file's status says when a name the user gave was not applied: the file is already here under another (#2130). */
 export declare function alreadyHereAs(name: string): string;
+/**
+ * Is an import into this receiver confidential (#2110)? Only when its
+ * destination is encrypted: a receiver that keeps into a sealed store
+ * (`keepsEncrypted`), or whose own door writes into one (`writesEncrypted`,
+ * #2118). No receiver can declare itself so otherwise.
+ */
+export declare function isConfidentialReceiver(receiver: Pick<RegisteredReceiver, 'keepsEncrypted' | 'writesEncrypted'> | undefined): boolean;
 /** Does this run keep its originals during the upload (#2034)? */
 export declare function keepsAtUpload(receiver: RegisteredReceiver | undefined, original: OriginalChoice): boolean;
 /** What keeping at upload did: how many it kept, or the first file it could not keep. */
@@ -110,10 +119,10 @@ export interface UploadKeepResult {
  * then queues nothing. Originals kept before it stay kept, and recorded, so
  * the next try reuses them.
  */
-export declare function keepOriginalsAtUpload(deps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, scope: string): Promise<UploadKeepResult>;
+export declare function keepOriginalsAtUpload(siteDeps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, scope: string): Promise<UploadKeepResult>;
 /**
  * Run one import. Fills and returns `report`, which the caller may be
  * showing while it runs. Never throws for one file's failure; that file's
  * status says why.
  */
-export declare function runImport(deps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, report: IceRunReport): Promise<IceRunReport>;
+export declare function runImport(siteDeps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, report: IceRunReport): Promise<IceRunReport>;

package/lib/src/ice/shims/csv.d.ts

@@ -54,6 +54,30 @@ export declare function parseCsv(text: string, delimiter?: string, skipLines?: n
  * invisible one.
  */
 export declare function preambleSuspicion(columns: readonly string[]): string | null;
+/**
+ * Clean CSV text before it is kept as a file (#2149): HTML is taken out of
+ * every cell, and a cell a spreadsheet would run as a formula gets a leading
+ * `'`, so it shows as text (the usual CSV-injection defence). Only the cells
+ * that change are rewritten, quoted; every other byte is kept as it was.
+ * Returns how many cells of each kind were cleaned.
+ */
+export declare function cleanCsvText(text: string, delimiter?: string): {
+    text: string;
+    html: number;
+    formulas: number;
+};
+/**
+ * How a CSV is read and written back for cleaning (#2149), so its bytes stay
+ * its own: UTF-16 with a byte-order mark as UTF-16; valid UTF-8 as UTF-8;
+ * anything else (Latin-1, Windows-1252 and the like) one byte to one
+ * character and back, which round-trips every byte exactly. The characters
+ * cleaning looks for (`, " < > = + - @`, tab, line ends) are ASCII, the same
+ * byte in each of these.
+ */
+export declare function csvEncoding(bytes: Buffer): {
+    text: string;
+    encode: (text: string) => Buffer;
+};
 /** One row as a record: its own id, or one synthesized from its content. */
 export declare function csvRecord(raw: RawRecord, opts: RecordShimOptions): IceRecordData | null;
 export declare const csvShim: IceShim;

package/lib/src/ice/shims/export.d.ts

@@ -0,0 +1,23 @@
+import type { ActorContext } from '../../context/ActorContext.js';
+import { type IceItem, type IceShim } from '../types.js';
+/** The core doors the export shims call. */
+export interface ExportShimDoors {
+    /** A complete HTML document for one NCM item (ExportManager's page document). */
+    renderDocument(item: IceItem): Promise<string>;
+    /** HTML → PDF (ExportManager.htmlToPdf), as the run's user. */
+    htmlToPdf(ctx: ActorContext, html: string): Promise<Buffer>;
+    /** Is a PDF provider chosen? */
+    pdfAvailable(): boolean;
+}
+/** A file name from a title: the title, with what no file system takes replaced. */
+export declare function exportFileName(item: IceItem, extension: string): string;
+/**
+ * The HTML with nothing in it that a renderer would fetch (#2120): only
+ * `data:` URLs are left, in attributes and in CSS. The local renderer
+ * already blocks the network; a remote one (`chrome-service`, Gotenberg)
+ * fetches what the HTML names, from where it runs, so this is done before
+ * the HTML leaves the process. Links (`<a href>`) stay: printing never
+ * follows them.
+ */
+export declare function withoutRemoteUrls(html: string): string;
+export declare function exportShims(doors: ExportShimDoors): IceShim[];

package/lib/src/ice/shims/index.d.ts

@@ -12,5 +12,7 @@
  * receiver that takes records (`receivers: ['*']`).
  */
 import type { IceShim } from '../types.js';
-/** Every record shim, in registration order. */
+/** Every record shim, in registration order. `core.csv` also cleans a CSV kept as a file (#2149). */
 export declare const RECORD_SHIMS: readonly IceShim[];
+/** Shims that only vet a file kept as a file (#2149): they clean and are never picked for a run. */
+export declare const VETTING_SHIMS: readonly IceShim[];

package/lib/src/ice/shims/svg.d.ts

@@ -0,0 +1,27 @@
+/**
+ * svg shim (#2149): cleans an SVG before it is kept as a file. An SVG is a
+ * document, not a picture: it can carry scripts, HTML inside
+ * `<foreignObject>`, `on…` event handlers, script links and animations that
+ * set a link. The file is parsed and rebuilt from an allow-list of SVG
+ * elements and attributes, never patched with patterns: what the parser did
+ * not take as an allowed element or attribute is not written back. The note
+ * says what kind of thing was removed and how many, never the content.
+ *
+ * The parser is the one the site already uses for author HTML
+ * (`src/rendering/htmlPolicy.ts`): sanitize-html on htmlparser2, here in XML
+ * mode so names keep their case. This file only configures it for SVG.
+ *
+ * Defence in depth, not the boundary: an uploaded file is always served
+ * sandboxed (`untrustedFileHeaders`, #1624), so nothing in it runs as the
+ * site. Cleaning keeps a file that is downloaded, embedded elsewhere or
+ * opened outside the site from carrying it.
+ *
+ * A vetting shim only (`clean`, no `read`): never picked for an import run.
+ */
+import type { IceShim, IceWarning } from '../types.js';
+/** The cleaned text and what was removed: the pure step behind the shim. */
+export declare function cleanSvgText(text: string): {
+    text: string;
+    removed: IceWarning[];
+};
+export declare const svgShim: IceShim;

package/lib/src/ice/shims/takeout.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `core.takeout` (#2118, ICE #1979): a download of a private store (#1387)
+ * handed back, into its owner's private store (`core.private-store`). It
+ * replaces the takeout import's own path (#1472).
+ *
+ * The engine unpacks the zip and hands each member here on its own, with the
+ * archive beside it (`IceItem.archive`); this shim reads the takeout's
+ * layout through that. What a takeout is, as #1387 writes it: one `{store}/`
+ * folder holding each page as `{title}.md` with full frontmatter, files under
+ * `attachments/`, and `files-index.json` mapping each file's id to its path
+ * in the archive. The reader is lenient about the one thing people change,
+ * the folder: someone who extracts a takeout and zips it again may add a
+ * level, or zip the contents with no folder at all, so the takeout's root is
+ * found rather than assumed.
+ *
+ * - A page (`.md` directly in the root) is one `takeout` item: its body as
+ *   text, and in `data` its title, uuid and frontmatter, and the files of
+ *   the takeout its body links to (`/attachments/{old id}`), so the
+ *   receiver can store those first and point the links at their new ids.
+ * - A file (directly in `attachments/`) is one `takeout` item: its bytes,
+ *   and in `data` its old id, name, media type and description from the index.
+ * - The file index is read through the archive by the members it names; on
+ *   its own it holds nothing to import (`skip`). So does anything else in
+ *   the archive: versions, the trash, footnotes and comments are not brought
+ *   back, as before.
+ *
+ * Pure: no I/O, no access decision, no write. The receiver's door does those.
+ */
+import type { IceShim } from '../types.js';
+/** The kind this shim produces: one page or one file of a takeout. */
+export declare const TAKEOUT_KIND = "takeout";
+/** The receiver a takeout goes into: its owner's private store. */
+export declare const PRIVATE_STORE_RECEIVER = "core.private-store";
+/** A file of the takeout that a page links to, found through the archive. */
+export interface TakeoutLinkedFile {
+    /** Its id where it came from: what the page's links name. */
+    oldId: string;
+    /** Its path in the archive. */
+    path: string;
+    name: string;
+    encodingFormat?: string;
+    description?: string;
+}
+/** A page of a takeout: the `data` of its item; the body is the item's `text`. */
+export interface TakeoutPageData {
+    entry: 'page';
+    /** From the frontmatter, else the file's name. */
+    title: string;
+    /** From the frontmatter. Absent for a page written by hand. */
+    uuid?: string;
+    /** The frontmatter, as written. */
+    metadata: Record<string, unknown>;
+    /** The takeout's files its body links to. */
+    files: TakeoutLinkedFile[];
+}
+/** A file of a takeout: the `data` of its item; the bytes are the item's `bytes`. */
+export interface TakeoutFileData {
+    entry: 'file';
+    /** Its id where it came from, when the file index names it. */
+    oldId?: string;
+    /** The name it was uploaded with. */
+    name: string;
+    encodingFormat?: string;
+    description?: string;
+}
+export type TakeoutData = TakeoutPageData | TakeoutFileData;
+/**
+ * The folder the takeout lives in: the one holding the file index, else the
+ * shallowest one holding a page. `''` is the archive's own root.
+ */
+export declare function takeoutRoot(paths: readonly string[]): string;
+/** `body` with every `/attachments/{old}` link pointed at its new id. */
+export declare function rewriteAttachmentLinks(body: string, ids: ReadonlyMap<string, string>): string;
+/** Whether `body` links to the file `id`. */
+export declare function linksToAttachment(body: string, id: string): boolean;
+/**
+ * The first free title of `title`, `title (imported)`, `title (imported 2)` …
+ * (operator, 2026-09-25): a DIFFERENT page already holding the title keeps
+ * it, and the import lands beside it.
+ */
+export declare function freeImportTitle(title: string, isTaken: (candidate: string) => Promise<boolean>): Promise<string>;
+/** The takeout shim: every member of a zip, read as a takeout's layout says. */
+export declare const takeoutShim: IceShim;

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

@@ -14,9 +14,10 @@
  *   noise filter, fingerprints, skipping unchanged files, per-file status,
  *   keeping the original, and running the work as a background job.
  *
- * Only importing is built in the first slice. `out` / `both` shims and the
- * `write` half are declared so export (#1974) and feeds (D10) fit later
- * without changing these shapes.
+ * - An __export source__ is the owner's door for reading the thing being
+ *   exported (#2120): a page, later a search result or an add-on's list. It
+ *   checks the owner's existing read permission (D5) and yields items that
+ *   `out` shims chain into one file to download.
  */
 import type { ActorContext } from '../context/ActorContext.js';
 import type { GuardedFetchOptions, GuardedResponse } from '../http/guardedFetch.js';
@@ -61,6 +62,28 @@ export interface IceItem {
      * (a feed entry): an item whose key the engine has seen before is skipped.
      */
     itemKey?: string;
+    /**
+     * The archive the file was unpacked from (#2118), when it was: what lies
+     * beside it, for a shim whose format spans the files of an archive (a
+     * takeout's pages link to its files by the ids its file index names).
+     * The engine still hands each file to the shims on its own.
+     */
+    archive?: IceArchiveView;
+}
+/**
+ * The archive a file was unpacked from (#2118): this file's own path in it,
+ * and every member, read only. Paths are the archive's own, `/`-separated.
+ * Never part of an item's key: what an item is, is its content.
+ */
+export interface IceArchiveView {
+    /** The archive's name, as the file's `name` begins: `takeout.zip`. */
+    name: string;
+    /** This file's path within the archive. */
+    path: string;
+    /** Every member's path, in the archive's order. */
+    paths: readonly string[];
+    /** A member's bytes, or undefined when there is no such member. */
+    read(memberPath: string): Buffer | undefined;
 }
 /**
  * The `data` of a `record` item (#2109): one row of a table or one entry of a
@@ -99,6 +122,14 @@ export interface ShimTools {
      */
     options: Record<string, unknown>;
 }
+/** What an `out` shim is handed (#2120): a shim's tools, and who the export is for. */
+export interface ExportShimTools extends ShimTools {
+    /**
+     * The job context of the user who asked for the export, for a core shim
+     * that calls a core door with it (the PDF render, P1).
+     */
+    ctx: ActorContext;
+}
 /** What a shim's read returns. */
 export interface ShimReadResult {
     items: IceItem[];
@@ -107,6 +138,13 @@ export interface ShimReadResult {
      * records plus a partial note): the file's status is then `partial`, with this.
      */
     partial?: string;
+    /**
+     * Set, with no items, when the file is part of its format's layout and
+     * holds nothing to import on its own (#2118): a takeout's file index, read
+     * through the archive by the files it names. The file's status is then
+     * `noise`, with this, and the ledger records nothing for it.
+     */
+    skip?: string;
 }
 /**
  * A shim as its author writes it (D7). `name` is unique within its owner; the
@@ -132,8 +170,47 @@ export interface IceShim {
     duplicates?: 'file' | 'item';
     /** Inbound: read one input. Required for `in` and `both`. */
     read?(input: IceItem, tools: ShimTools): Promise<ShimReadResult>;
-    /** Outbound (export, #1974): not run in the first slice. Required for `out` and `both`. */
-    write?(items: IceItem[], tools: ShimTools): Promise<IceItem[]>;
+    /**
+     * Outbound (export, #2120): turn the items into this shim's `produces`.
+     * Required for `out` and `both`. An outbound shim matches its input by
+     * `accepts.kinds` alone; a shim that produces `file` makes the download,
+     * and is what the Export action offers.
+     */
+    write?(items: IceItem[], tools: ExportShimTools): Promise<IceItem[]>;
+    /**
+     * An outbound shim whose engine is missing says so (#2120): PDF with no
+     * provider chosen. The Export action does not offer it. Default: available.
+     */
+    isAvailable?(): boolean;
+    /**
+     * Vetting (#2149): clean this format's own kind of risky content out of a
+     * file that is about to be kept as a file (scripts and handlers in an SVG,
+     * HTML and formulas in CSV cells). Returns the cleaned bytes, and one note
+     * per kind of thing removed, saying what and how many, never the content.
+     * An inbound shim has `read()`, `clean()` or both; one with only `clean()`
+     * is never picked for a run.
+     */
+    clean?(input: IceItem): Promise<IceCleanResult>;
+}
+/** What a shim's `clean` returns (#2149). `removed` is empty when the file needed nothing. */
+export interface IceCleanResult {
+    bytes: Buffer;
+    removed: IceWarning[];
+}
+/**
+ * A file after the engine's vetting (#2149): its type read from its bytes,
+ * and, when its format's shim found something to clean, the cleaned bytes
+ * and what was removed. The caller keeps `bytes`, never the bytes it sent.
+ */
+export interface IceVetResult {
+    name: string;
+    bytes: Buffer;
+    /** From the bytes when they show it (#1624), else the declared or extension type. */
+    mediaType: string;
+    /** What cleaning removed, one note per kind; empty when nothing was. */
+    removed: IceWarning[];
+    /** The shim that cleaned it, when one did. */
+    cleanedBy?: string;
 }
 /** A shim the engine holds: its full id, and who registered it. */
 export interface RegisteredShim extends IceShim {
@@ -214,6 +291,18 @@ export interface ReceiveInfo {
      * taken there: never a silent replace.
      */
     givenName?: string;
+    /**
+     * The place within the receiver the run goes to (#2118), for a receiver
+     * with `targets`: one its `targets` gave the user the run is for, checked
+     * by the engine before the run. The receiver's door still checks it.
+     */
+    target?: string;
+    /**
+     * Set when the file was taken before and is read again only because the
+     * receiver `rechecks` this item (#2171): the receiver's own check decides
+     * whether it still holds it, and one it holds is `duplicate`.
+     */
+    rechecked?: boolean;
 }
 /** What a receiver's `fileDone` is told (#2109). */
 export interface FileDoneInfo extends ReceiveInfo {
@@ -236,6 +325,11 @@ export interface ReceiveOutcome {
      */
     heldAs?: string;
 }
+/** A place within a receiver (#2118): a user's private store. */
+export interface IceTarget {
+    id: string;
+    label?: string;
+}
 /**
  * A receiver as its owner writes it (D4). Its doors are the receiver's own
  * existing ones; each checks its own permission with the context given (D5).
@@ -294,6 +388,49 @@ export interface IceReceiver {
      * before the run is queued; the run reuses what was kept and needs no key.
      */
     keepsEncrypted?: boolean;
+    /**
+     * `receive` itself may write into an encrypted store (a takeout into a
+     * sealed private store, #2118), which only a request holding the user's
+     * unlocked key can write. The engine then runs an upload into it during
+     * the upload request, with the request's own context, instead of as a
+     * background job: no key is ever carried into a job (#2034's decision).
+     * An import into it is confidential (#2110). Core's only: an add-on
+     * receiver that declares it is refused at registration, so an add-on is
+     * confidential only through `keepsEncrypted`.
+     */
+    writesEncrypted?: boolean;
+    /**
+     * A zip inside an uploaded zip is handed on as a file, not unpacked
+     * (#2118): for a receiver whose format holds zips as content (a takeout's
+     * files). Without it, the engine unpacks nested zips too.
+     */
+    innerZipsAsFiles?: boolean;
+    /**
+     * The items this receiver checks for itself whether it still holds
+     * (#2118, operator 2026-10-30): a takeout's page, by its uuid, and a
+     * takeout's file, by its bytes (#2171), so one deleted since an earlier
+     * import comes back when the same takeout is imported again. A file whose
+     * fingerprint the scope already took is then read again, and only these
+     * of its items go to `receive`, with `info.rechecked`; the rest are
+     * duplicates. When nothing new is stored it stays `unchanged`, unrecorded,
+     * as the fingerprint skip leaves it. Without this, the fingerprint decides.
+     */
+    rechecks?(item: IceItem): boolean;
+    /**
+     * The places within this receiver this context may import into (#2118):
+     * a user's own private stores. The receiver's own rule (D5). A receiver
+     * with targets takes a run only with one of them (`IceRunRequest.target`),
+     * which the engine checks against this before the run, binds into the
+     * ledger scope, and hands on in every item's `ReceiveInfo.target`.
+     */
+    targets?(ctx: ActorContext): Promise<IceTarget[]>;
+    /**
+     * Called once when a run into this receiver has read every file (#2118),
+     * with its report: a receiver that records the run as one act (a
+     * takeout's `store-import` audit event). Not called for a refused run. A
+     * throw is the run's failure.
+     */
+    runDone?(ctx: ActorContext, report: IceRunReport): Promise<void>;
     /** The original-file choices this receiver offers (D11). Without it: all three. */
     originals?: IceOriginalChoices;
     /**
@@ -321,6 +458,8 @@ export interface IceUpload {
      * drops it on a zip). Checked by the engine against the receiver's `names`.
      */
     givenName?: string;
+    /** The archive the engine unpacked this file from (#2118); set by the engine, never by a caller. */
+    archive?: IceArchiveView;
 }
 /**
  * A URL the engine fetches as the run's one file (D1, D10, #2109): through
@@ -378,6 +517,12 @@ export interface IceRunRequest {
      * client sent.
      */
     options?: Record<string, unknown>;
+    /**
+     * The place within the receiver (#2118), for a receiver with `targets`:
+     * one of those it gives the user the run is for. Required for such a
+     * receiver and refused for any other.
+     */
+    target?: string;
 }
 /** Per-file status (first slice). */
 export type IceFileStatus = 'imported' | 'partial' | 'unchanged' | 'duplicate' | 'noise' | 'unreadable' | 'refused' | 'failed';
@@ -410,6 +555,8 @@ export interface IceFileReport {
 export interface IceRunReport {
     runId: string;
     receiver: string;
+    /** The place within the receiver (#2118), when it has places. */
+    target?: string;
     scope: string;
     /** Who it ran as. */
     username: string;
@@ -461,6 +608,9 @@ export interface RecentImport {
     /** The receiver it went into. */
     receiver: string;
     receiverLabel?: string;
+    /** The place within it (#2118), when the receiver has places. */
+    target?: string;
+    targetLabel?: string;
     /** How many references the receiver gave (pages, records). */
     refs: number;
     /** Where the user can open the first of them (`linkFor`), when they may. */
@@ -482,3 +632,99 @@ export interface IceLedger {
     recordItems(scope: string, itemKeys: string[]): Promise<void>;
     files(scope: string): Promise<LedgerFileEntry[]>;
 }
+/**
+ * The kind of the one item an export ends with: a file to download, with
+ * `bytes`, `mediaType` and the `name` it is saved under.
+ */
+export declare const EXPORT_FILE_KIND = "file";
+/** What an export source is told about the read it is asked for. */
+export interface ExportReadInfo {
+    /** The shim that will make the file (`core.pdf`). */
+    format: string;
+}
+/**
+ * The owner's door for reading the thing being exported (#2120, D5): a page
+ * through PageManager, later a search result or an add-on's list. Export
+ * starts from the thing (operator, 2026-10-28): the source says what kind of
+ * items it yields, and only the `out` shims that can make a file from that
+ * kind are offered.
+ */
+export interface IceExportSource {
+    name: string;
+    label?: string;
+    /** The kind of the items it yields, e.g. `ncm` for a page. */
+    yields: IceKind;
+    /**
+     * Would this context be allowed to export `ref`? Asked only to decide
+     * whether to offer the Export action: an affordance, which records nothing.
+     * The owner's existing read rule (D5).
+     */
+    mayExport(ref: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Read `ref` for export as `ctx`: the door. It checks the owner's existing
+     * permission, records what its owner records, and answers null when the
+     * thing is not there or `ctx` may not export it, without telling the two apart.
+     */
+    read(ref: string, ctx: ActorContext, info: ExportReadInfo): Promise<IceItem[] | null>;
+    /**
+     * Record how an export of `ref` ended, as its owner records exports: once
+     * the run has ended, with the file made or not. Also called, as a failure,
+     * when what was read is not exported (too large, the site too busy).
+     * Optional; a record that fails is logged, never thrown.
+     */
+    recordExport?(ref: string, ctx: ActorContext, outcome: ExportOutcome): Promise<void>;
+}
+/** How an export ended, for its source's record (#2120). */
+export interface ExportOutcome {
+    /** The shim that made, or was to make, the file. */
+    format: string;
+    runId: string;
+    /** The names of the items the source read. */
+    items: string[];
+    result: 'success' | 'failure';
+    /** Why it failed, as the user is told. */
+    reason?: string;
+}
+export interface RegisteredExportSource extends IceExportSource {
+    id: string;
+    owner: string;
+}
+/** A format the Export action offers: the shim that makes the file, and the shims before it. */
+export interface IceExportFormat {
+    /** The shim that makes the file, `core.pdf`. */
+    id: string;
+    label: string;
+    /** Every shim the export runs through, in order, ending with `id`. */
+    chain: string[];
+}
+/** One export, as a caller asks for it. */
+export interface IceExportRequest {
+    /** The export source's id, `core.pages`. */
+    source: string;
+    /** What to export, in the source's own terms: a page's name. */
+    ref: string;
+    /** The format: an id `exportFormatsFor` offered. */
+    format: string;
+}
+/** The file an export made, as its status shows it. */
+export interface IceExportFile {
+    name: string;
+    mediaType: string;
+    size: number;
+}
+export interface IceExportReport {
+    runId: string;
+    source: string;
+    ref: string;
+    format: string;
+    chain: string[];
+    /** Who it ran as: the only user who sees it or downloads its file. */
+    username: string;
+    state: 'queued' | 'running' | 'done' | 'failed';
+    startedAt?: string;
+    finishedAt?: string;
+    error?: string;
+    file?: IceExportFile;
+    /** When the file is let go (`ngdpbase.export.engine.keep-minutes`). */
+    expiresAt?: string;
+}

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

@@ -0,0 +1,19 @@
+import type { IceUpload, IceVetResult, RegisteredShim } from './types.js';
+/** A file whose format's shim failed while cleaning it: it is not kept, since it could not be checked. */
+export declare class IceVetRefused extends Error {
+    readonly file: string;
+    readonly reason: string;
+    constructor(file: string, reason: string);
+}
+/**
+ * The shim that cleans this file: one whose media types include the type the
+ * bytes show; or, when the bytes show no type of their own (CSV, plain text),
+ * one whose extensions include the file's. Its "can I read this?" must agree.
+ */
+export declare function cleanerFor(shims: readonly RegisteredShim[], name: string, mediaType: string, bytesShowType: boolean): RegisteredShim | null;
+/**
+ * Vet one file (#2149). `shims` are the enabled ones. Throws
+ * {@link IceVetRefused} when the cleaning shim fails: a file that could not
+ * be checked is not kept.
+ */
+export declare function vetFile(shims: readonly RegisteredShim[], upload: IceUpload): Promise<IceVetResult>;