@jwilleke/ngdpbase-types 5.27.0 → 5.29.0

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

@@ -36,9 +36,12 @@ 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, IceUpload, IceSource, IceRunRequest, IceRunReport, IceFileReport, IceFileStatus } from '../../src/ice/types.js';
+export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, IceUpload, IceSource, IceRunRequest, IceRunReport, IceFileReport, IceFileStatus } from '../../src/ice/types.js';
+export type { default as UserManager, UserUpdateInput, UserUpdateFn } from '../../src/managers/UserManager.js';
+export type { User, UserPreferences } from '../../src/types/User.js';
 export type { default as PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
 export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
 export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';
 export type { Organization, OrganizationInput, OrganizationUpdate } from '../../src/types/Organization.js';
 export type { ContactRefusedError } from '../../src/utils/contactAccess.js';
+export type { default as RoleManager } from '../../src/managers/RoleManager.js';

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

@@ -13,8 +13,8 @@
  * the call arrived under, and the address it came from. What does not: roles.
  * Authority is resolved at the moment of each decision, never carried.
  */
-import type { PermissionSubject } from '../managers/UserManager.js';
-import type { JobContext } from './JobContext.js';
+import type { PermissionSubject, JobSubject } from '../managers/UserManager.js';
+import { type JobContext } from './JobContext.js';
 export type ActorContext = PermissionSubject | JobContext;
 /**
  * The fields an audit record takes from a context.
@@ -35,6 +35,19 @@ export interface ActorAttribution {
     metadata: Record<string, unknown>;
 }
 export declare function isJobContext(ctx: ActorContext): ctx is JobContext;
+/**
+ * The one place a context becomes the subject a decision reads (#2022).
+ *
+ * Called by the deciders — `PolicyDecisionPoint` (`decide`, `permits`,
+ * `holds`) and `PolicyInformationPoint`'s page questions — and by nobody
+ * else: a caller hands them its context as given. A `JobContext` carries
+ * identity, never authority, so it becomes a `JobSubject` whose roles policy
+ * resolves now, keeping its token, share and proxy claims
+ * (`toPermissionSubject`). Anything else is already a subject and passes
+ * through. The object guard is #1173's: `'x' in 'jim'` throws. Not part of
+ * the add-on API; `npm run lint:context` holds callers to it.
+ */
+export declare function decisionSubject<S extends PermissionSubject | JobSubject>(input: ActorContext | S | null | undefined): PermissionSubject | JobSubject | S | null | undefined;
 /**
  * Who acted, for the record — read from the context, never guessed.
  *

package/lib/src/context/ActorContext.js

@@ -1,8 +1,28 @@
+import { toPermissionSubject } from './JobContext.js';
 import { attributedTo } from './bootActions.js';
 import { proxyAttribution } from '../utils/proxyClaim.js';
 export function isJobContext(ctx) {
     return 'origin' in ctx && 'requestedAt' in ctx;
 }
+/**
+ * The one place a context becomes the subject a decision reads (#2022).
+ *
+ * Called by the deciders — `PolicyDecisionPoint` (`decide`, `permits`,
+ * `holds`) and `PolicyInformationPoint`'s page questions — and by nobody
+ * else: a caller hands them its context as given. A `JobContext` carries
+ * identity, never authority, so it becomes a `JobSubject` whose roles policy
+ * resolves now, keeping its token, share and proxy claims
+ * (`toPermissionSubject`). Anything else is already a subject and passes
+ * through. The object guard is #1173's: `'x' in 'jim'` throws. Not part of
+ * the add-on API; `npm run lint:context` holds callers to it.
+ */
+export function decisionSubject(input) {
+    if (typeof input !== 'object' || input === null)
+        return input;
+    // A JobSubject is not an ActorContext, and is not a job context either.
+    const ctx = input;
+    return isJobContext(ctx) ? toPermissionSubject(ctx) : input;
+}
 /**
  * Who acted, for the record — read from the context, never guessed.
  *

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

@@ -40,21 +40,34 @@ export declare class ApiError extends Error {
      * offer the way forward, as core routes do (`{ error, reauth }`).
      */
     readonly reauth?: string | undefined;
+    /**
+     * For a refusal because the user has documents to accept (#2027): this
+     * site's consent prompt, returning to the page they were on. Sent with
+     * the 403 as `consent`; a page is redirected there.
+     */
+    readonly consent?: string | undefined;
     constructor(status: number, message: string, 
     /**
      * For a step-up refusal (#1745): where the person re-authenticates,
      * returning to the page they were on. Send it with the 403 so the page can
      * offer the way forward, as core routes do (`{ error, reauth }`).
      */
-    reauth?: string | undefined);
+    reauth?: string | undefined, 
+    /**
+     * For a refusal because the user has documents to accept (#2027): this
+     * site's consent prompt, returning to the page they were on. Sent with
+     * the 403 as `consent`; a page is redirected there.
+     */
+    consent?: string | undefined);
 }
 /**
  * Send a refusal — the one way it reaches the client, from core routes and
  * every add-on route alike (#1749). JSON is `{ success: false, error, reauth? }`;
  * text is the message, then where to sign in again for a step-up refusal.
- * `page` is for a link the person followed in the browser: a step-up refusal
- * redirects to the re-authenticate page, a 401 to sign-in (returning here),
- * anything else is the message as text. A route never writes its own refusal:
+ * `page` is for a link the user followed or a form they sent in the browser:
+ * a step-up refusal redirects to the re-authenticate page, a consent refusal
+ * to the consent prompt (#2027), a 401 to sign-in (returning here), anything
+ * else is the message as text. JSON carries the consent link as `consent`. A route never writes its own refusal:
  * the step-up `reauth` is easy to drop.
  */
 export declare function sendApiError(res: Response, err: ApiError, mode?: ReauthMode): void;

package/lib/src/context/ApiContext.js

@@ -4,6 +4,7 @@
 import '../types/express.js';
 import { BaseContext } from './BaseContext.js';
 import { STEP_UP_REASON } from '../types/Policy.js';
+import { CONSENT_PATH } from '../types/Consent.js';
 // ── ApiError ────────────────────────────────────────────────────────────────
 /**
  * Thrown by ApiContext guard methods (requirePermission, actingUsername).
@@ -12,16 +13,24 @@ import { STEP_UP_REASON } from '../types/Policy.js';
 export class ApiError extends Error {
     status;
     reauth;
+    consent;
     constructor(status, message, 
     /**
      * For a step-up refusal (#1745): where the person re-authenticates,
      * returning to the page they were on. Send it with the 403 so the page can
      * offer the way forward, as core routes do (`{ error, reauth }`).
      */
-    reauth) {
+    reauth, 
+    /**
+     * For a refusal because the user has documents to accept (#2027): this
+     * site's consent prompt, returning to the page they were on. Sent with
+     * the 403 as `consent`; a page is redirected there.
+     */
+    consent) {
         super(message);
         this.status = status;
         this.reauth = reauth;
+        this.consent = consent;
         this.name = 'ApiError';
     }
 }
@@ -29,19 +38,26 @@ export class ApiError extends Error {
  * Send a refusal — the one way it reaches the client, from core routes and
  * every add-on route alike (#1749). JSON is `{ success: false, error, reauth? }`;
  * text is the message, then where to sign in again for a step-up refusal.
- * `page` is for a link the person followed in the browser: a step-up refusal
- * redirects to the re-authenticate page, a 401 to sign-in (returning here),
- * anything else is the message as text. A route never writes its own refusal:
+ * `page` is for a link the user followed or a form they sent in the browser:
+ * a step-up refusal redirects to the re-authenticate page, a consent refusal
+ * to the consent prompt (#2027), a 401 to sign-in (returning here), anything
+ * else is the message as text. JSON carries the consent link as `consent`. A route never writes its own refusal:
  * the step-up `reauth` is easy to drop.
  */
 export function sendApiError(res, err, mode = 'json') {
     // Only this site's re-authenticate page: an add-on's ApiError cannot send the person elsewhere.
     const reauth = typeof err.reauth === 'string' && err.reauth.startsWith('/auth/reauth?') ? err.reauth : undefined;
+    // Likewise only this site's consent prompt.
+    const consent = typeof err.consent === 'string' && (err.consent === CONSENT_PATH || err.consent.startsWith(`${CONSENT_PATH}?`)) ? err.consent : undefined;
     if (mode === 'page') {
         if (reauth) {
             res.redirect(reauth);
             return;
         }
+        if (consent) {
+            res.redirect(consent);
+            return;
+        }
         if (err.status === 401) {
             res.redirect('/login?redirect=' + encodeURIComponent(res.req?.originalUrl || '/'));
             return;
@@ -50,10 +66,10 @@ export function sendApiError(res, err, mode = 'json') {
         return;
     }
     if (mode === 'text') {
-        res.status(err.status).send(reauth ? `${err.message}: ${reauth}` : err.message);
+        res.status(err.status).send(reauth ? `${err.message}: ${reauth}` : consent ? `${err.message} Read and accept them at ${consent}` : err.message);
         return;
     }
-    res.status(err.status).json({ success: false, error: err.message, ...(reauth ? { reauth } : {}) });
+    res.status(err.status).json({ success: false, error: err.message, ...(reauth ? { reauth } : {}), ...(consent ? { consent } : {}) });
 }
 /**
  * The subject a request carries, refused when there is none (#1399).

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

@@ -43,6 +43,32 @@ export interface ChainSpec {
  * warnings first. Partial notes are collected into `partial`.
  */
 export declare function convertChain(shim: RegisteredShim, input: IceItem, chain: string[], spec: ChainSpec, partial: string[]): Promise<ChainLeaf[]>;
+/** 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. */
+export interface UploadKeepResult {
+    kept: number;
+    refused?: {
+        name: string;
+        message: string;
+    };
+}
+/**
+ * Keep the originals of a run whose receiver keeps into an encrypted store,
+ * now, during the upload (#2034). `ctx` is the REQUEST's context: it holds
+ * the user's unlocked key, so the receiver's `keepOriginal` seals the bytes
+ * and the store's sealed index entry while the key is live. Each kept
+ * original is recorded in the ledger by fingerprint and door (#2011), so the
+ * queued run reuses it and never keeps again.
+ *
+ * The files are decided exactly as the run decides them ({@link planFile}):
+ * noise, a file too large, one nothing reads and one already imported are
+ * not kept. An original already kept through this door is not kept again.
+ * Stops at the first refusal (or failure) and says which file: the caller
+ * 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>;
 /**
  * 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

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

@@ -121,6 +121,16 @@ export interface RegisteredShim extends IceShim {
 }
 /** D11: what the person importing chose to do with the original file. */
 export type OriginalChoice = 'cite' | 'keep' | 'none';
+/**
+ * D11: the original-file choices a receiver offers, and which one is chosen
+ * when the user picks none (#2021). The import screen offers only `allowed`,
+ * and the engine refuses a run asking for any other.
+ */
+export interface IceOriginalChoices {
+    allowed: OriginalChoice[];
+    /** One of `allowed`. Default: `ngdpbase.import.engine.default-original` when allowed, else the first allowed. */
+    default?: OriginalChoice;
+}
 /** A citation to the origin (D11): the receiver renders it, as a footnote on a page. */
 export interface IceCitation {
     name: string;
@@ -172,6 +182,15 @@ export interface IceReceiver {
      * store). Without this, `keep` hands the original to the files receiver.
      */
     keepOriginal?(original: IceItem, ctx: ActorContext): Promise<ReceiveOutcome>;
+    /**
+     * `keepOriginal` writes into an encrypted store (phr's vault), which only a
+     * request holding the user's unlocked key can write (#2034). The engine then
+     * keeps each original during the upload, with the request's own context,
+     * before the run is queued; the run reuses what was kept and needs no key.
+     */
+    keepsEncrypted?: boolean;
+    /** The original-file choices this receiver offers (D11). Without it: all three. */
+    originals?: IceOriginalChoices;
 }
 export interface RegisteredReceiver extends IceReceiver {
     id: string;
@@ -238,6 +257,14 @@ export interface IceRunReport {
     error?: string;
     files: IceFileReport[];
 }
+/**
+ * A kept original as the ledger remembers it, with the door that kept it
+ * (a receiver's own `keepOriginal`, or `core.files`). A later run of the same
+ * fingerprint through the same door reuses it instead of keeping another copy.
+ */
+export interface LedgerOriginal extends KeptOriginal {
+    door: string;
+}
 /** What the engine remembers about one file in a scope. */
 export interface LedgerFileEntry {
     name: string;
@@ -247,6 +274,8 @@ export interface LedgerFileEntry {
     message?: string;
     at: string;
     refs: string[];
+    /** The original kept for this fingerprint, whatever became of the conversion (D11). */
+    original?: LedgerOriginal;
 }
 /**
  * Where the engine keeps fingerprints, per-file status and item keys, per

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

@@ -121,8 +121,12 @@ export interface AddonModule {
      * "section was not rendered at all" (addon disabled mid-session, cached
      * form). Without it, absent checkbox fields look identical to "user
      * submitted no such field" and you may silently clobber stored values.
+     *
+     * `ctx` is the signed-in user's own context, forwarded from the request:
+     * pass it to your manager's door (and to the PDP) instead of rebuilding a
+     * subject from `user` (#2018).
      */
-    profileSection?(user: AddonProfileUser): Promise<AddonProfileSection | null> | AddonProfileSection | null;
+    profileSection?(user: AddonProfileUser, ctx: ActorContext): Promise<AddonProfileSection | null> | AddonProfileSection | null;
     /**
      * Optional save handler paired with `profileSection()` (#534).
      *
@@ -673,7 +677,7 @@ declare class AddonsManager extends BaseManager {
      * Result order follows registration order of the addons map so the
      * displayed section order is stable across renders.
      */
-    getProfileSections(user: AddonProfileUser): Promise<AddonProfileSectionEntry[]>;
+    getProfileSections(user: AddonProfileUser, ctx: ActorContext): Promise<AddonProfileSectionEntry[]>;
     /**
      * #1234: say at load when an addon still implements the pre-#1234 hook.
      *
@@ -689,7 +693,7 @@ declare class AddonsManager extends BaseManager {
      * `saveProfileSection()` handler (#534).
      *
      * Runs SEQUENTIALLY — each addon's read-modify-write of user preferences
-     * (typical implementation: `getUser → merge → updateUser`) must see the
+     * (`updateUser`'s function form, #2025) must see the
      * previous addon's writes. Parallel execution would create a same-snapshot
      * race where two addons read identical preferences, each merge their own
      * keys, and the second writer clobbers the first writer's changes.

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

@@ -67,10 +67,11 @@ declare class AssetManager extends BaseManager {
     /**
      * Return all AssetRecords referenced by the given page slug.
      *
-     * O(1) index lookup + one getById() call per referenced asset.
+     * O(1) index lookup + one provider lookup per referenced asset.
      * Stale entries (asset deleted or provider removed) are silently filtered out.
+     * Nothing for a caller who may not read assets (`asset-read`, #2018).
      */
-    getAssetsForPage(slug: string): Promise<AssetRecord[]>;
+    getAssetsForPage(ctx: ActorContext, slug: string): Promise<AssetRecord[]>;
     /**
      * Remove a page's entry from the reverse index.
      * Call this when a page is deleted or renamed.
@@ -103,8 +104,11 @@ declare class AssetManager extends BaseManager {
     /**
      * Retrieve a single asset by id.  If providerId is given only that provider
      * is checked; otherwise all providers are tried in registration order.
+     * Null for a caller who may not read assets (`asset-read`, asked of the PDP
+     * with `ctx`, as FileManager asks for the public place; #2018).
      */
-    getById(id: string, providerId?: string): Promise<AssetRecord | null>;
+    getById(ctx: ActorContext, id: string, providerId?: string): Promise<AssetRecord | null>;
+    private lookup;
     /**
      * Generate or retrieve a cached thumbnail.
      * Requires the provider to declare the 'thumbnail' capability.

package/lib/src/managers/ExportManager.js

@@ -539,6 +539,11 @@ class ExportManager extends BaseManager {
      * @returns {Promise<void>}
      */
     async deleteExport(filename) {
+        // Only a plain file name inside the export folder: never a path that
+        // reaches another folder.
+        if (!filename || filename !== path.basename(filename) || filename === '.' || filename === '..') {
+            throw new Error(`Not an export file name: ${filename}`);
+        }
         const filePath = path.join(this.exportDirectory, filename);
         await fs.unlink(filePath);
         logger.info(`Deleted export: ${filename}`);

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

@@ -32,7 +32,7 @@ import type { WikiEngine } from '../types/WikiEngine.js';
 import { IContentConverter } from '../converters/IContentConverter.js';
 import { type ZipReadLimits } from '../utils/zipArchive.js';
 import { type JobContext } from '../context/JobContext.js';
-import type { IceLedger, IceReceiver, IceRunReport, IceRunRequest, IceShim, RegisteredShim } from '../ice/types.js';
+import type { IceLedger, IceOriginalChoices, IceReceiver, IceRunReport, IceRunRequest, IceShim, RegisteredShim } from '../ice/types.js';
 /**
  * Options for import operations
  */
@@ -207,6 +207,16 @@ export declare class TakeoutImportRefused extends Error {
     readonly reason: 'not-owner' | 'no-such-store' | 'locked' | 'unreadable';
     constructor(reason: 'not-owner' | 'no-such-store' | 'locked' | 'unreadable', message: string);
 }
+/**
+ * An import refused at upload, before anything was queued (#2034): keeping
+ * the original of `file` in the receiver's encrypted store was refused or
+ * failed. `message` is written for the user who uploaded.
+ */
+export declare class ImportUploadRefused extends Error {
+    readonly file: string;
+    readonly reason: string;
+    constructor(file: string, reason: string);
+}
 /** One page's outcome in a takeout import (#1472). */
 export type TakeoutPageOutcome = {
     title: string;
@@ -253,6 +263,12 @@ export type TakeoutImportReport = {
      */
     reportPage?: string;
 };
+/** A receiver the import screen may offer this user (#2021): its id, label and original-file choices (D11). */
+export interface UsableReceiver {
+    id: string;
+    label?: string;
+    originals: Required<IceOriginalChoices>;
+}
 /**
  * Import Manager class
  *
@@ -310,11 +326,24 @@ declare class ImportManager extends BaseManager {
     listShims(): Array<Pick<RegisteredShim, 'id' | 'owner' | 'label' | 'direction' | 'produces' | 'receivers'> & {
         enabled: boolean;
     }>;
-    /** The receivers this context may use (D5): each answers with its own existing permission. */
-    receiversFor(ctx: ActorContext): Promise<Array<{
-        id: string;
-        label?: string;
-    }>>;
+    /**
+     * The receivers this context may use (D5): each answers with its own
+     * existing permission. Each comes with the original-file choices it offers
+     * (D11), for the import screen (#2021).
+     */
+    receiversFor(ctx: ActorContext): Promise<UsableReceiver[]>;
+    /**
+     * The original-file choices a receiver offers (D11, #2021): what it
+     * declares, else all three; its default when it names one it allows, else
+     * `ngdpbase.import.engine.default-original` when allowed, else the first.
+     */
+    private originalChoices;
+    /**
+     * 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;
     /**
      * 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
@@ -325,17 +354,37 @@ declare class ImportManager extends BaseManager {
     runImport(request: IceRunRequest, ctx: ActorContext): Promise<IceRunReport>;
     /**
      * Queue an import as background work and return its run id at once. The
-     * run carries `ctx` — the person who asked (`jobContextFromRequest`), or a
+     * run carries `ctx` — the user who asked (`jobContextFromRequest`), or a
      * job's context with its reason — and each receiver checks its own
-     * permission with it when the run reaches it (D5).
+     * permission with it when the run reaches it (D5). A user's upload, from
+     * a request, goes through {@link enqueueUpload} instead.
      */
     enqueueImport(request: IceRunRequest, ctx: JobContext): Promise<string>;
+    /**
+     * Queue a user's upload, from the request it arrived in (#2034). `ctx` is
+     * the REQUEST's context; the run carries the job context derived from it
+     * (`jobContextFromRequest`), as {@link enqueueImport} does.
+     *
+     * When the run keeps originals through a receiver that keeps into an
+     * encrypted store (`keepsEncrypted`), they are kept first, here, with
+     * `ctx`, while the user's key is in the request: the bytes are sealed and
+     * 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.
+     *
+     * @throws ImportUploadRefused when an original could not be kept; nothing is queued
+     */
+    enqueueUpload(request: IceRunRequest, ctx: ActorContext): Promise<string>;
+    private enqueueResolved;
     /** A run's report, to the person it runs as; null to anyone else. */
     getImportRun(runId: string, ctx: ActorContext): IceRunReport | null;
+    /** The runs this process holds for the user `ctx` names, newest first (#2021): their own, never anyone else's. */
+    importRunsFor(ctx: ActorContext): IceRunReport[];
     /** Use this ledger instead of the file one: a test's, or a database table's. */
     setImportLedger(ledger: IceLedger): void;
     private newRunReport;
     private executeRun;
+    /** What a run, or keeping at upload, works with. */
+    private iceDeps;
     private enabledShims;
     /**
      * Hand the queue to the background job. One job run drains every queued

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

@@ -88,13 +88,15 @@ declare class OrganizationManager extends BaseManager {
      * problem actually bites.
      */
     getInstallOrg(): Promise<Organization | null>;
-    getById(id: string): Promise<Organization | null>;
-    getByFile(filename: string): Promise<Organization | null>;
+    /** One organization by `@id`, for a caller who may read contacts (`contact-read`), or core's own work (#2018). */
+    getById(ctx: ActorContext, id: string): Promise<Organization | null>;
+    /** One organization by its file name, decided as {@link getById} (#2018). */
+    getByFile(ctx: ActorContext, filename: string): Promise<Organization | null>;
     /** #1006: how many organizations this instance holds. Count only. */
     getManagerStats(): Promise<ManagerStats>;
     /** 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`). */
+    /** One organization by `@id`: {@link getById}. */
     get(ctx: ActorContext, id: string): Promise<Organization | null>;
     /**
      * Organizations whose `name`, `legalName`, `email` or a contact point's

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

@@ -1128,6 +1128,38 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * const deleted = await pageManager.deletePage('Old Page', req.userContext);
      */
     deletePage(identifier: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Delete the pages a test made (#2008): every shared page carrying the
+     * `test-artifact` system keyword (#1355), and never a page without it.
+     * `only` narrows the set further — a deleted test account's profile is
+     * `{ author, systemCategory: 'user-profile' }`.
+     *
+     * Each page is recorded as `page-delete` before it is deleted (on-failure
+     * refuse: a page whose record cannot be written is not deleted), then goes
+     * through {@link deletePage}, so the delete is soft and the shared indexes
+     * follow. One page's failure never stops the rest; it is reported.
+     *
+     * The caller decides who may ask: the sweep route asks `admin-system`, and
+     * an account delete has already been decided as `user-delete`. Private
+     * vault pages are not in the shared index, so they are not reached here.
+     *
+     * @param ctx - Who is acting; named in every record
+     * @param only - Narrow to one author and/or system-category
+     */
+    deleteTestArtifacts(ctx: ActorContext, only?: {
+        author?: string;
+        systemCategory?: string;
+    }): Promise<{
+        deleted: Array<{
+            title: string;
+            uuid: string;
+        }>;
+        failed: Array<{
+            title: string;
+            uuid: string;
+            error: string;
+        }>;
+    }>;
     /**
      * The name a page was reached by, as the shared indexes key it: a private
      * page's path (#1456), else its title — the caller may have used a uuid or

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

@@ -23,8 +23,13 @@ export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' |
  * `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).
+ *
+ * Every lookup takes the caller's context too (#2018): `getById`,
+ * `getByIdentifier` and `getByUserIdentifier`. A user reads their own identity
+ * record, and `update` changes it, under `profile-manage`; anyone else's needs
+ * `contact-read` / `contact-manage`. Core's own reads (RoleManager resolving
+ * roles on every request, UserManager's account lifecycle) pass the system
+ * context, allowed without a policy evaluation (`requireRecordAccess`).
  *
  * A later sign-up joins a person with no account in one of two ways: the new
  * account confirms an emailed link (`offerSignUpLink` → `confirmSignUpLink`),
@@ -32,8 +37,8 @@ export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' |
  * 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.
  *
- * `getByUserIdentifier(username)` remains as a lazy-migration entry point
- * for legacy users that pre-date the sync wiring.
+ * `getByUserIdentifier(ctx, username)` returns a user's identity record and
+ * makes it when the user has none (#2037): every user has exactly one.
  */
 declare class PersonManager extends BaseManager {
     readonly description = "Canonical Person records (#617)";
@@ -46,6 +51,8 @@ declare class PersonManager extends BaseManager {
     private metricsRef;
     /** Sign-up link offers by token (#1930). In memory: a restart drops them, and an administrator links by hand. */
     private linkOffers;
+    /** #2037: making a user's missing identity record, one at a time per username. */
+    private readonly accountRecords;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /** `ngdpbase.application.persons.storagedir`, resolved: where the records are. */
@@ -56,15 +63,26 @@ declare class PersonManager extends BaseManager {
      */
     backupFolders(): BackupFolder[];
     getProvider(): PersonProvider | null;
-    getById(id: string): Promise<Person | null>;
-    getByIdentifier(identifier: string): Promise<Person | null>;
+    /**
+     * One identity record by `@id` (#2018): the caller's own under
+     * `profile-manage`, anyone else's under `contact-read`, core's own work
+     * under the system context. A refusal throws `ContactRefusedError`.
+     */
+    getById(ctx: ActorContext, id: string): Promise<Person | null>;
+    /**
+     * The identity record whose `identifier` is `identifier` (a username, or a
+     * contact's `person:<uuid>`), decided as {@link getById} before it is read.
+     */
+    getByIdentifier(ctx: ActorContext, identifier: string): Promise<Person | null>;
+    private cachedById;
+    private cachedByIdentifier;
     /** #1006: how many people this instance holds. Count only, never records. */
     getManagerStats(): Promise<ManagerStats>;
     /** 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`). */
+    /** One person by `@id`: {@link getById}, the caller's own under `profile-manage`, anyone else's under `contact-read`. */
     get(ctx: ActorContext, id: string): Promise<Person | null>;
     /**
      * Persons whose name (`name`, `givenName`, `familyName`) or `email` contains
@@ -82,7 +100,11 @@ declare class PersonManager extends BaseManager {
      * 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. */
+    /**
+     * Change a person's fields, affiliations included. `@id` and `identifier`
+     * never change here. The caller's own identity record under
+     * `profile-manage`, anyone else's under `contact-manage` (#2018).
+     */
     update(ctx: ActorContext, id: string, patch: PersonUpdate): Promise<Person | null>;
     delete(ctx: ActorContext, id: string): Promise<boolean>;
     /**
@@ -123,7 +145,10 @@ declare class PersonManager extends BaseManager {
      * 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. */
+    /**
+     * Each affiliation names an organization that exists, looked up with the
+     * caller's context; `role` is trimmed text. Throws on any other shape.
+     */
     private checkedAffiliations;
     private configNumber;
     /**
@@ -132,13 +157,22 @@ declare class PersonManager extends BaseManager {
      */
     invalidateCache(): void;
     /**
-     * Lazy-migration entry point.
+     * The identity record of the user `username`, made when the user has none
+     * (#2037). Every user has exactly one identity record; one made outside
+     * `UserManager.createUser` (an account written straight into the user
+     * store) gets it here, from the account's display name and email.
      *
-     * Returns the Person paired to `username`. If none exists and a matching
-     * User does, a Person is created from the User's email/displayName and
-     * persisted. Subsequent calls return the persisted record.
+     * The read is decided as {@link getByIdentifier} (#2018): a signed-in user's
+     * own under `profile-manage`, anyone else's under `contact-read`, core's own
+     * work under the system context. Making the missing record is core's
+     * bookkeeping, not the caller's contact management, so it goes through
+     * {@link create} under the system context, naming the caller, and is
+     * recorded as `contact-manage`. One at a time per username, so two lookups
+     * never make two records. Null when there is no account by that name.
+     * Never a second record: a contact with the same email is left alone
+     * (an administrator links it, {@link linkAccount}).
      */
-    getByUserIdentifier(username: string): Promise<Person | null>;
+    getByUserIdentifier(ctx: ActorContext, username: string): Promise<Person | null>;
     private requireProvider;
     private getMetrics;
     private normalizeProviderName;