@jwilleke/ngdpbase-types 5.33.0 → 5.35.0

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

@@ -320,6 +320,33 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * with no person behind it are refused. A refusal reads 'Permission denied'
      * so the route answers it as one (401 for an anonymous caller).
      */
+    /**
+     * Once, at start-up (#2097): the shared pool's uploaders and editors become
+     * identity @ids (`IdentityManager.convertRecordedUser`: an orphan for a
+     * name with no account, `orphan:unknown` for the pool's `Unknown`), written
+     * once through the provider, under the system context. A second start
+     * writes nothing. Counts only in the log; orphans on the dashboard. When the
+     * identity store cannot answer, nothing is written and the next start tries
+     * again. A vault's files convert when the vault is opened
+     * ({@link convertVaultUploaders}).
+     */
+    convertUploadersAtBoot(): Promise<void>;
+    /**
+     * The uploaders in the vaults of the context's own user that it can open
+     * (#2097), when they are opened: at sign-in and unlock. Each vault's files
+     * index, through its own I/O. Nothing is written when the identity store
+     * cannot answer; the next opening tries again.
+     */
+    convertVaultUploaders(ctx: ActorContext): Promise<number>;
+    /** Counts only, never a name (#2097). */
+    private reportUploaderConversion;
+    /** The identity store could not answer: nothing is converted this start, and the next start tries again (#2097). */
+    private postponeUploaderConversion;
+    /**
+     * What a file record stores for the user `username` (#2097): their identity
+     * @id, or the username when there is none or the identity store cannot answer.
+     */
+    private userReference;
     private static uploaderOf;
     /** A file is added to a private page only by someone who may edit it: the page's own decision (#1398). */
     private assertMayEditPage;

package/lib/src/managers/BackupManager.js

@@ -1200,7 +1200,7 @@ class BackupManager extends BaseManager {
     async notifyAdmins(level, title, message) {
         try {
             await this.engine.getManager('NotificationManager')
-                ?.addNotification({ type: 'system', level, title, message });
+                ?.notifyAdmins({ level, title, message });
         }
         catch (err) {
             logger.error(`❌ The notification '${title}' could not be sent:`, err);
@@ -2059,8 +2059,8 @@ class BackupManager extends BaseManager {
         catch (err) {
             jobs.registerJob(def);
             logger.error(`❌ Automatic backups are ON but NOT scheduled: ${err.message}. Fix the setting in Admin → Backup.`);
-            void this.engine.getManager('NotificationManager')?.addNotification({
-                type: 'system', level: 'error', title: 'Automatic backups are not running',
+            void this.engine.getManager('NotificationManager')?.notifyAdmins({
+                level: 'error', title: 'Automatic backups are not running',
                 message: `${err.message}. Fix the setting in Admin → Backup.`
             }).catch(() => undefined);
         }

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

@@ -10,6 +10,31 @@ export default class CommentManager extends BaseManager {
     private readonly outsideCheck;
     constructor(engine: WikiEngine);
     initialize(): Promise<void>;
+    /**
+     * Once, at start-up (#2041): every public comment whose `author` is still a
+     * username gets `IdentityManager.convertReference`'s answer, one write per
+     * comment file, under the system context: that user's identity `@id`, or
+     * `orphan:<name>` when the name has no account (nobody's from then on: a
+     * later account with that name never takes it over, and only an
+     * administrator can delete it). `@id`s, orphans, `anonymous` and the system
+     * principal are left alone, so a second start writes nothing. Orphans are
+     * reported, counts only: a log line and the admin dashboard's
+     * needs-attention list. When the identity store cannot answer, the whole
+     * pass is postponed to the next start and reported the same way. A vault
+     * page's comments are in its vault, which start-up does not open; they keep
+     * their username, and {@link isAuthor} still matches it.
+     * `authorDisplayName` and `deletedBy` are not touched.
+     */
+    private convertAuthorsToIdentityIds;
+    /** The identity store could not answer: nothing more is converted this start, and the next start tries again (#2041). */
+    private postponeConversion;
+    /**
+     * Whether `ctx` wrote `comment` (#2041): its `author` is the caller's
+     * identity `@id`, or, on a comment written before and not yet converted (a
+     * vault page's), the caller's username. An orphan (`orphan:<name>`) is
+     * nobody's and never matches.
+     */
+    isAuthor(comment: Pick<PageComment, 'author'>, ctx: ActorContext): Promise<boolean>;
     /** `ngdpbase.comments.storagedir`, resolved, or the default when there is no configuration (a test). */
     private configuredDir;
     /**

package/lib/src/managers/DatabaseManager.js

@@ -713,7 +713,7 @@ class DatabaseManager extends BaseManager {
     async notify(level, title, message) {
         try {
             await this.engine.getManager('NotificationManager')
-                ?.addNotification({ type: 'system', level, title, message });
+                ?.notifyAdmins({ level, title, message });
         }
         catch (err) {
             logger.error(`[DatabaseManager] The notification '${title}' could not be sent (#1723):`, err);

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

@@ -7,6 +7,7 @@ export interface PageFootnote {
     display: string;
     url: string;
     note: string;
+    /** Who added it: their identity `@id` (#2041); a username on a note written before and not yet converted (a vault page's), or one with no account. */
     createdBy: string;
     createdAt: string;
 }
@@ -17,6 +18,32 @@ export default class FootnoteManager extends BaseManager {
     private readonly outsideCheck;
     constructor(engine: WikiEngine);
     initialize(): Promise<void>;
+    /**
+     * Once, at start-up (#2041): every public footnote whose `createdBy` is
+     * still a username gets `IdentityManager.convertReference`'s answer, one
+     * write per page file, under the system context: that user's identity
+     * `@id`, or `orphan:<name>` when the name has no account (nobody's from
+     * then on: a later account with that name never takes it over, and only an
+     * administrator can delete it). `@id`s, orphans, `anonymous` and the system
+     * principal are left alone, so a second start writes nothing. Orphans are
+     * reported, counts only (the legacy `migrated` placeholder is `orphan:migrated`
+     * and only logged at info, not counted: it has no recorded creator): a log line and the admin dashboard's
+     * needs-attention list. When the identity store cannot answer, the whole
+     * pass is postponed to the next start and reported the same way. A vault
+     * page's footnotes are in its vault, which start-up does not open; they
+     * keep their username, and {@link isCreator} still matches it.
+     */
+    private convertCreatorsToIdentityIds;
+    /** The identity store could not answer: nothing more is converted this start, and the next start tries again (#2041). */
+    private postponeConversion;
+    /**
+     * Whether `ctx` added `footnote` (#2041): its `createdBy` is the caller's
+     * identity `@id`, or, on a footnote written before and not yet converted
+     * (a vault page's), the caller's username. An orphan (`orphan:<name>`)
+     * is nobody's and never matches; neither does the legacy `migrated`
+     * placeholder (no recorded creator), on a footnote not yet converted.
+     */
+    isCreator(footnote: Pick<PageFootnote, 'createdBy'>, ctx: ActorContext): Promise<boolean>;
     /** `ngdpbase.footnotes.storagedir`, resolved, or the default when there is no configuration (a test). */
     private configuredDir;
     /**

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

@@ -272,6 +272,120 @@ declare class IdentityManager extends BaseManager {
      * (an administrator links it, {@link linkAccount}).
      */
     getByUserIdentifier(ctx: ActorContext, username: string): Promise<Person | null>;
+    /**
+     * The `@id` of the user `username`'s identity record, or null (#2041): null
+     * when there is no account by that name, and null when the identity store
+     * cannot answer (degraded, unreadable), logged without the name. The door
+     * for a write or a record that refers to a user: it then keeps working as
+     * it does for a name with no account, and never fails because the identity
+     * store is down. Read as {@link getByUserIdentifier}, which a caller that
+     * must tell "no account" from "cannot answer" uses instead (a start-up
+     * conversion, with {@link canAnswer}). A refusal still throws.
+     */
+    identityIdOf(ctx: ActorContext, username: string): Promise<string | null>;
+    /**
+     * What a stored reference to a user should become, for a start-up
+     * conversion (#2041). `stored` is what a record holds today:
+     *
+     * - an `@id` (`urn:`), an orphan (`orphan:<name>`), `anonymous`, the
+     *   system principal or an empty value: `kept` (`orphan` when it is an
+     *   orphan, so the caller can count them);
+     * - a username with an account: that identity's `@id`, `converted`;
+     * - a username with no account: `orphan:<name>`, `orphaned`. The record is
+     *   then nobody's: a later account with the same name never takes it over,
+     *   and no "is it mine" check matches it.
+     *
+     * Throws when the identity store cannot answer (and so does nothing to the
+     * record): the caller postpones its whole pass to the next start, rather
+     * than orphan a name it could not look up. Ask {@link canAnswer} first.
+     */
+    convertReference(ctx: ActorContext, stored: string): Promise<{
+        value: string;
+        outcome: 'kept' | 'orphan' | 'converted' | 'orphaned';
+    }>;
+    /**
+     * Whether the identity store can answer lookups now (#2041): false when it
+     * started degraded (no provider). A start-up conversion asks this first and
+     * postpones the whole pass when it is false.
+     */
+    canAnswer(): boolean;
+    /**
+     * {@link convertReference} for records that may hold a value meaning "no
+     * user was recorded" (#2097): `migrated`, `unknown`, `import`
+     * ({@link NO_RECORDED_USER}) become `orphan:<value>` without a lookup,
+     * outcome `no-user`, so an account that later takes one of those names
+     * gains nothing, and the caller does not count them as needing attention.
+     * Everything else is `convertReference`'s, and throws as it does.
+     */
+    convertRecordedUser(ctx: ActorContext, stored: string): Promise<{
+        value: string;
+        outcome: 'kept' | 'orphan' | 'converted' | 'orphaned' | 'no-user';
+    }>;
+    /**
+     * What a new record stores for the user `username` (#2097): their identity
+     * `@id`; a "no user recorded" value (`migrated`, `unknown`, `import`) as
+     * its orphan form, so no account ever gains it; a principal (`anonymous`,
+     * the system principal), an `@id` or an orphan as it is; a name with no
+     * account, or any name when the store cannot answer ({@link identityIdOf}),
+     * as given. The one rule for page authors and editors, tombstones and file
+     * uploaders.
+     */
+    storedReferenceOf(ctx: ActorContext, username: string): Promise<string>;
+    /**
+     * One start-up conversion pass over stored references (#2097): `convert`
+     * is {@link convertRecordedUser}'s value, and `counts` tallies its outcomes
+     * (values converted to an @id, orphans found or made, "no user recorded"
+     * values) for the caller's counts-only report. When the store cannot
+     * answer it throws `IdentityStoreUnavailableError`, so the caller postpones
+     * its pass rather than skip a record.
+     */
+    conversionPass(ctx: ActorContext): {
+        convert: (stored: string) => Promise<string>;
+        counts: {
+            converted: number;
+            orphans: number;
+            noUser: number;
+        };
+    };
+    /**
+     * Whether a stored reference names the user `username` (#2097): it is their
+     * identity `@id`, or, on a record not yet converted, their username. An
+     * orphan (`orphan:<name>`) and a "no user recorded" value never match
+     * anyone, so a later account with the same name inherits nothing. The `@id`
+     * is looked up with {@link identityIdOf}: false when the store cannot answer.
+     */
+    refersTo(ctx: ActorContext, stored: unknown, username: string | null | undefined): Promise<boolean>;
+    /**
+     * The stored values that name the user `username` (#2097): their identity
+     * `@id` and, for records not yet converted, their username — the batch form
+     * of {@link refersTo}, for a list filter that compares many records (the
+     * page index, the search index). A "no user recorded" name is left out, and
+     * no orphan is ever in it. Only the username when the store cannot answer.
+     */
+    referencesOf(ctx: ActorContext, username: string | null | undefined): Promise<string[]>;
+    /**
+     * The username a stored reference names (#2097), for code that needs the
+     * sign-in name (a vault path, a preference): an `@id` gives its account's
+     * username, an orphan gives null, anything else (a username not yet
+     * converted, `anonymous`, the system principal) is returned as it is. Null
+     * for an `@id` with no account (deleted, or a contact's) and when the store
+     * cannot answer, logged without the value; a refusal still throws.
+     */
+    usernameOf(ctx: ActorContext, stored: unknown): Promise<string | null>;
+    /**
+     * How a stored reference to a user is shown to people (#2097, operator
+     * 2026-10-26): the username followed by the id, `jim (urn:uuid:3f6c…)`. An
+     * orphan shows as `jim (no account)`, an `@id` whose account is gone as
+     * `urn:uuid:… (no account)`; anything else (a username not yet converted,
+     * `anonymous`, the system principal) as it is. Resolved when shown, never
+     * stored. Never throws for a store that is down.
+     *
+     * `ctx` is whoever the name is shown to. Showing who wrote a page needs no
+     * `identity-read`: only the username and the id are shown, as a page always
+     * showed its author's username, so the record is read as core's own lookup
+     * (the system context, naming the caller in its reason).
+     */
+    describeReference(ctx: ActorContext, stored: unknown): Promise<string>;
     private requireProvider;
     private getMetrics;
     private normalizeProviderName;

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

@@ -10,9 +10,11 @@ export interface Notification {
     title: string;
     message: string;
     level: 'info' | 'warning' | 'error' | 'success';
+    /** Who it is for, by identity `@id` (#2041); empty means every user. A name with no account is kept as given. */
     targetUsers: string[];
     createdAt: Date;
     expiresAt: Date | null;
+    /** Who dismissed it, by identity `@id` (#2041); a name with no account as given. */
     dismissedBy: string[];
 }
 /**
@@ -23,6 +25,7 @@ export interface NotificationInput {
     title?: string;
     message?: string;
     level?: 'info' | 'warning' | 'error' | 'success';
+    /** Usernames or identity `@id`s; stored as `@id`s (#2041). Empty or absent: every user. */
     targetUsers?: string[];
     expiresAt?: Date | null;
     /**
@@ -32,6 +35,8 @@ export interface NotificationInput {
      */
     escalate?: boolean;
 }
+/** A notice for administrators: the type and the audience are not the caller's to choose. */
+export type AdminNoticeInput = Omit<NotificationInput, 'type' | 'targetUsers'>;
 /**
  * Notification statistics
  */
@@ -92,6 +97,21 @@ declare class NotificationManager extends BaseManager {
      * Load notifications from storage
      */
     private loadNotifications;
+    /**
+     * Once, at start-up (#2041): every stored `targetUsers` and `dismissedBy`
+     * entry that is still a username gets `IdentityManager.convertReference`'s
+     * answer, under the system context, and the file is written once: that
+     * user's identity `@id`, or `orphan:<name>` when the name has no account
+     * (it then reaches nobody: a later account with that name is never
+     * addressed by it). `@id`s, orphans, `anonymous` and the system principal
+     * are left alone, so a second start writes nothing. Orphans are reported,
+     * counts only: a log line and the admin dashboard's needs-attention list.
+     * When the identity store cannot answer, nothing is changed and the pass is
+     * postponed to the next start, reported the same way.
+     */
+    private convertRecipientsToIdentityIds;
+    /** The identity store could not answer: nothing is converted this start, and the next start tries again (#2041). */
+    private postponeConversion;
     /**
      * Save notifications to storage
      */
@@ -115,6 +135,16 @@ declare class NotificationManager extends BaseManager {
      * @returns false when there is no such notification
      */
     updateNotificationMessage(notificationId: string, message: string): Promise<boolean>;
+    /**
+     * The one way to tell administrators something (#2040): a `system`
+     * notification targeted at the users holding `admin-system`. A notification
+     * with no targetUsers reaches every user, so no admin notice is created any
+     * other way. Nobody holds admin-system: the log line stands alone and null is
+     * returned.
+     *
+     * @returns the notification id, or null when there was nobody to tell
+     */
+    notifyAdmins(input: AdminNoticeInput): Promise<string | null>;
     /**
      * Add a notification (alias for createNotification for backward compatibility)
      * @param {NotificationInput} notification - Notification object
@@ -122,12 +152,14 @@ declare class NotificationManager extends BaseManager {
      */
     addNotification(notification: NotificationInput): Promise<string>;
     /**
-     * Get notifications for a specific user
-     * @param {string} username - Username to get notifications for
+     * The notifications for the caller: addressed to every user, or to them by
+     * identity `@id` (#2041), or by username on one with no account; never one
+     * they dismissed.
+     * @param ctx - Who is asking: the request's subject, forwarded
      * @param {boolean} includeExpired - Include expired notifications
-     * @returns {Notification[]} Array of notifications
+     * @returns Array of notifications
      */
-    getUserNotifications(username: string, includeExpired?: boolean): Notification[];
+    getUserNotifications(ctx: ActorContext, includeExpired?: boolean): Promise<Notification[]>;
     /**
      * Dismiss a notification for the caller.
      *

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

@@ -120,9 +120,10 @@ declare class OrganizationManager extends BaseManager {
         affiliation: PersonAffiliation;
     }>>;
     /**
-     * Create an organization. `name` is required; `@id` defaults to the `url`,
-     * else a new `urn:uuid:`. `filename` is for the install anchor (seeding);
-     * other records take one from the url or name.
+     * Create an organization. `name` is required. Its `@id` is always a new
+     * `urn:uuid:` (#2041): the web address stays the ordinary `url` field, and
+     * an `@id` the caller gives is ignored. `filename` is for the install
+     * anchor (seeding); other records take one from the url or name.
      */
     create(ctx: ActorContext, org: OrganizationInput, filename?: string): Promise<Organization>;
     update(ctx: ActorContext, id: string, patch: OrganizationUpdate): Promise<Organization | null>;

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

@@ -258,6 +258,31 @@ export declare const CAPTURE_VAULT_MIGRATION = "capture-vault";
 export declare const CATEGORY_VAULT_MIGRATION = "category-vaults";
 /** Private slugs from `private--…` to `vaults--…` (#1507). */
 export declare const VAULT_SLUG_MIGRATION = "vault-slugs";
+/** Page authorship stored as identity @ids (#2097): every page and its history visited once; recorded per site and per vault. */
+export declare const AUTHORSHIP_ID_MIGRATION = "authorship-identity-ids";
+/** What one authorship conversion pass did (#2097), counts only. */
+export interface AuthorshipConversion {
+    /** `done`, or `postponed` when the identity store could not answer. */
+    status: 'done' | 'postponed';
+    /** Every page visited (`full`), or only those whose index entry still names a username. */
+    full: boolean;
+    pagesVisited: number;
+    pagesChanged: number;
+    /** Pages whose frontmatter could not be rewritten line by line, left as they are. */
+    pagesRefused: number;
+    versionsChanged: number;
+    tombstonesChanged: number;
+    converted: number;
+    orphans: number;
+    /** Orphans on shipped (documentation, system) and add-on pages: their author is upstream's, not a site user; not needing attention. */
+    shippedOrphans: number;
+    noUser: number;
+    /** Pages and tombstones skipped for their own reason (a file that cannot be read or written, a full disk, a vault that cannot be opened). */
+    pagesSkipped: number;
+    /** The error class of each skip (`EACCES`, `ENOSPC`, ...), never a message, name or path. */
+    skipErrors: string[];
+    ms: number;
+}
 /**
  * Minimal WikiContext interface for type safety
  * TODO: Convert WikiContext.js to TypeScript and import proper type
@@ -377,6 +402,15 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * #754 backfill (v3.33.0).
      */
     readonly types: readonly SchemaType[];
+    /** One write at a time per page, by uuid (#2097), when the provider keeps no such lock itself. */
+    private readonly pageWrites;
+    /**
+     * Run `task` as the only write on page `key` (#2097): saves, deletes, the
+     * authorship conversion, and the provider's own restores and purges. The
+     * lock is the provider's (`withPageWrite`), so its trash work takes the same
+     * one; a provider without it gets this manager's.
+     */
+    private pageWrite;
     /**
      * On-disk schema version for the page-frontmatter shape (Decision 6).
      * Bump when the persisted Article-relevant fields on a page change. v1 is
@@ -867,6 +901,12 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * @throws PageContentValidationError when a filter reports severity 'error'
      */
     private assertContentPasses;
+    /**
+     * What a page stores for the user `name` (#2097): `IdentityManager.storedReferenceOf`.
+     */
+    private referenceTo;
+    /** `audience` and each `access[action]` of a save, user entries as {@link referenceTo} stores them (#2097). */
+    private convertAccessListsForSave;
     /**
      * The frontmatter a save writes, from the frontmatter it was given (#1462).
      *
@@ -1415,6 +1455,12 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * feed. New code should prefer this over enumerating getAllPages().
      */
     getRecentChanges(ctx: ActorContext, options?: RecentChangesOptions): Promise<RecentChangeEntry[]>;
+    /**
+     * A principal list (roles and the username) with the user's identity @id
+     * added (#2097), so a listing matches an access-list entry stored as the
+     * @id as the page view does (`PolicyInformationPoint` principals).
+     */
+    private principalsWithIdentityId;
     /**
      * Every indexed page carrying an `addon` provenance stamp.
      * Used by addon orphan detection; reads the in-memory index, no disk I/O.
@@ -1440,15 +1486,25 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * `creator` only.
      */
     getPagesByCreator(username: string, ctx: ActorContext, options?: GetPagesByCreatorOptions): Promise<RecentChangeEntry[]>;
+    /**
+     * The stored values that name `username` (#2097): their identity @id and, for
+     * pages not yet converted, the username (`IdentityManager.referencesOf`), so
+     * "my pages" lists converted and unconverted pages alike and an orphan never.
+     */
+    private referencesOf;
     /**
      * Pages most recently edited by a user (#640 Phase 2).
      */
     getPagesByEditor(username: string, ctx: ActorContext, options?: PagesScanOptions): Promise<RecentChangeEntry[]>;
     /**
      * Pages whose frontmatter audience matches any of the caller's principals,
-     * excluding pages the caller already owns (#640 Phase 2).
+     * excluding pages the caller already owns (#640 Phase 2). `options.username`
+     * names the caller, so a page whose author is their identity @id counts as
+     * theirs (#2097).
      */
-    getPagesSharedWith(principals: string[], options?: PagesScanOptions): Promise<RecentChangeEntry[]>;
+    getPagesSharedWith(principals: string[], options?: PagesScanOptions & {
+        username?: string;
+    }): Promise<RecentChangeEntry[]>;
     /**
      * The private-container decision for a page (docs/private-stores.md,
      * Access). PolicyInformationPoint's Tier 0 asks this, so every `canAccess` on a page —
@@ -1538,6 +1594,74 @@ declare class PageManager extends BaseManager implements CatalogSource {
     migrateVaultUrlsInPublicPages(ctx: ActorContext): Promise<number>;
     /** Every vault on disk, as `owner/store` — encrypted ones included, since only their folder names are read. */
     private listVaults;
+    /**
+     * The page-authorship conversion at start-up (#2097), on the public pages:
+     * best-effort, never throws, and runs while the site serves (WikiEngine does
+     * not wait for it). See {@link convertAuthorship}.
+     */
+    convertAuthorshipAtBoot(): Promise<AuthorshipConversion | null>;
+    /**
+     * Convert the public pages' authorship to identity @ids (#2097, operator
+     * 2026-10-26), through this door's own write path, one page at a time
+     * with the saves ({@link pageWrite}):
+     *
+     * - each page's frontmatter `author` and `editor`, written without
+     *   touching its body, its other fields or its `lastModified`, and without
+     *   a new version; its page index entry follows;
+     * - its version history's editors (`manifest.json`), in place;
+     * - the tombstones' `author`, `editor` and `deletedBy`;
+     * - then the search index, rebuilt from the pages once if anything changed.
+     *
+     * Each value gets `IdentityManager.convertRecordedUser`'s answer: a
+     * username with an account becomes its @id; one with none `orphan:<name>`
+     * (counted, and on the dashboard: only an administrator acts on those
+     * pages); `migrated`, `unknown` and `import` `orphan:<value>` without a
+     * lookup (counted apart, not needing attention); @ids, orphans and
+     * principals are kept, so a second run writes nothing.
+     *
+     * The first complete pass visits every page and its history, and is then
+     * recorded in the site's migrations record; later passes visit only pages
+     * whose index entry still holds a value to convert. Pages are taken in
+     * batches of `ngdpbase.page.authorship-conversion.batch-size`, yielding
+     * between batches. When the identity store cannot answer (`canAnswer()`
+     * false, or a lookup fails mid-pass) the pass stops, says so on the
+     * dashboard, and the next start tries again. Logs counts only. Vault pages
+     * convert when their vault is opened ({@link convertVaultAuthorship}).
+     */
+    convertAuthorship(ctx: ActorContext): Promise<AuthorshipConversion | null>;
+    /**
+     * The authorship conversion for the vaults of `owner` this context can open
+     * (#2097), when they are opened: at sign-in and unlock, where the owner's
+     * keys are live. Each vault's pages (frontmatter, its own page index entry,
+     * history, access lists) and the owner's vault trash; each vault is
+     * recorded as done in its own migrations record and skipped from then on.
+     * Postponed, and tried at the next opening, when the identity store cannot
+     * answer; a page or tombstone that fails for its own reason is skipped and
+     * counted, and keeps its vault from being recorded as done.
+     */
+    convertVaultAuthorship(ctx: ActorContext, owner: string): Promise<AuthorshipConversion | null>;
+    /**
+     * How a frontmatter `audience` or `access[action]` entry converts (#2097):
+     * an entry naming a user becomes their identity @id with the pass's own rule
+     * (`orphan:<name>` for a name with no account, counted); every other kind is
+     * kept as written: a role (declared in `ngdpbase.roles.definitions` or held
+     * as a role record), the pseudo-roles `All`, `Authenticated`, `Anonymous`
+     * and `Asserted`, an `addon:`/`job:` or any other `kind:` entry, an @id or
+     * an orphan. A name that is both a role and a username stays the role.
+     */
+    private accessListConverter;
+    /** Every role name a principal list may hold, lower-cased (#2097): declared roles, role records, and the pseudo-roles. */
+    private roleNames;
+    /** Whether an index entry still holds an author or editor the conversion would change (#2097). No lookup is written. */
+    private authorshipNeedsConversion;
+    /** The system-categories whose pages are shipped with the code (source `shipped`), lower-cased (#2097). */
+    private shippedCategories;
+    /** `ngdpbase.page.authorship-conversion.batch-size`: pages converted between yields (#2097). */
+    private authorshipBatchSize;
+    /** Counts only, never a name (#2097): the log, and the dashboard for orphans and refused pages. */
+    private reportAuthorshipConversion;
+    /** The identity store could not answer: nothing more is converted this start, and the next start tries again (#2097). */
+    private postponeAuthorshipConversion;
     /**
      * Rewrite `[Title]` to `[store/Title]` in the private pages that mean it.
      *

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

@@ -187,7 +187,7 @@ declare class RoleManager extends BaseManager {
      * unless the caller sends one for a whole batch. Returns the error to throw.
      */
     private roleFailure;
-    /** An error notification for admins; a notification that cannot be sent is logged, never thrown. */
+    /** An error notification for the users holding `admin-system`; a notification that cannot be sent is logged, never thrown. */
     private reportToAdmins;
     /** #2015: the membership queue's key for one role record. */
     private membershipKey;

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

@@ -45,6 +45,10 @@ interface AdvancedSearchOptions {
     };
     /** #774: which date field `dateRange` filters on. Default `'modified'`. */
     dateField?: 'modified' | 'created';
+    /** A username, or several: pages whose author is that user (#2097: their identity @id or, not yet converted, the username). */
+    author?: string | string[];
+    /** As `author`, for the last editor. */
+    editor?: string | string[];
     [key: string]: unknown;
 }
 /**
@@ -240,6 +244,12 @@ declare class SearchManager extends BaseManager {
      * });
      */
     advancedSearchWithContext(wikiContext: WikiContext, options?: AdvancedSearchOptions): Promise<SearchResult[]>;
+    /**
+     * The stored values a search for `who` matches (#2097): for each username,
+     * that user's identity @id and the username (`IdentityManager.referencesOf`).
+     * Without IdentityManager, the values as given.
+     */
+    private referencesOf;
     /**
      * Search for pages matching the query
      *

package/lib/src/parsers/MarkupParser.d.ts

@@ -414,6 +414,15 @@ declare class MarkupParser extends BaseManager {
      * claiming a page is missing.
      */
     private resolvePrivateLinkTitles;
+    /**
+     * The username a PUBLIC page's author names, for a `[store/Title]` link on
+     * it (#1457, #2097): the author is stored as an identity @id, and a vault is
+     * named by its owner's username, so the @id is resolved once per parse
+     * through IdentityManager. Null when a caller already said who the owner
+     * is, on a private page (its name carries the owner), on a page with no
+     * such link, and for an author that names no account.
+     */
+    private resolveAuthorOwner;
     generateCacheKey(content: string, context: ParseContextData): string;
     /**
      * Extract style blocks using state-stack parsing for proper nesting support

package/lib/src/parsers/context/ParseContext.d.ts

@@ -186,6 +186,12 @@ declare class ParseContext {
      * Resolved once per parse by MarkupParser, never per link.
      */
     privateLinkTitles: Map<string, Set<string>> | null;
+    /**
+     * The username of a public page's author, when the author is stored as an
+     * identity @id (#2097): what a `[store/Title]` link on it resolves in.
+     * Resolved once per parse by MarkupParser; null when not needed.
+     */
+    pageOwner: string | null;
     /**
      * Hand finished HTML from a syntax handler to MarkupParser; write the
      * returned placeholder into the content instead (#1623). The HTML is merged

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

@@ -101,10 +101,14 @@ export interface SearchCriteria {
     statuses?: string[];
     /** Fields to search in (title, content, category, keywords, or all) */
     searchIn?: string[];
-    /** Author to filter by (page creator — matches metadata.author) */
-    author?: string;
-    /** Editor to filter by (last modifier — matches metadata.editor) */
-    editor?: string;
+    /**
+     * Author to filter by (page creator — matches metadata.author). A list
+     * matches any of its values: SearchManager turns a username into the
+     * values that name that user, their identity @id and the username (#2097).
+     */
+    author?: string | string[];
+    /** Editor to filter by (last modifier — matches metadata.editor); a list as for `author`. */
+    editor?: string | string[];
     /** Date range */
     dateRange?: {
         from?: string;

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

@@ -203,6 +203,20 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
      * @private
      */
     private saveMetadata;
+    /**
+     * The shared pool's uploaders and editors (#2097): each record's
+     * `author.name` and `editor.name` become what `convert` answers (the
+     * identity @id), and the metadata file is written once when anything
+     * changed. `convert` may throw (the identity store cannot answer); then
+     * nothing is written. Returns how many values changed.
+     */
+    convertPoolReferences(convert: (stored: string) => Promise<string>): Promise<number>;
+    /**
+     * One vault's uploaders (#2097): each entry's `author` in the vault's own
+     * files index, through the vault's I/O. Written once when anything
+     * changed; nothing when `convert` throws. Returns how many values changed.
+     */
+    convertStoreReferences(location: StoreFileLocation, convert: (stored: string) => Promise<string>): Promise<number>;
     /**
      * Generate unique attachment ID using SHA-256 hash of content
      * @param buffer - File data

package/lib/src/providers/databaseMigrations.js

@@ -117,6 +117,20 @@ const DATABASE_MIGRATIONS = [
             db.exec('CREATE INDEX review_requests_by_status ON review_requests (status, filed_at)');
             db.exec('CREATE INDEX review_requests_by_decided ON review_requests (decided_at)');
         }
+    },
+    {
+        // #2041: a row names the owner of its resource by identity @id in
+        // `metadata.owner` and by username in `metadata.ownerUser`, so the rows
+        // about an account can still be listed after the account (and its
+        // identity record) is deleted. This column is the copy of `ownerUser`
+        // for the index; rows written before it are null, and their `owner` is
+        // the username anyway.
+        id: '20261026120000',
+        description: 'audit log: audit_events.owner_user',
+        up: (db) => {
+            db.exec('ALTER TABLE audit_events ADD COLUMN owner_user TEXT');
+            db.exec('CREATE INDEX audit_events_by_owner_user ON audit_events (owner_user, timestamp)');
+        }
     }
 ];
 export default DATABASE_MIGRATIONS;

package/lib/src/security/PolicyInformationPoint.d.ts

@@ -188,6 +188,13 @@ declare class PolicyInformationPoint extends BaseManager {
      * a role its user holds left the job out.
      */
     private matchableNow;
+    /**
+     * The subject as matched, carrying its identity @id (#2097): page access
+     * lists name users by @id. Matching only: the subject is never changed for
+     * any other use. No lookup for nobody or a reserved name; null when the
+     * identity store cannot answer, and then only entries not yet converted match.
+     */
+    private withIdentityId;
     /**
      * Who is making this request: the subject the session middleware resolved,
      * else the session's account resolved now, else the anonymous visitor.
@@ -357,6 +364,14 @@ declare class PolicyInformationPoint extends BaseManager {
      *   audience terms by the NCM funnel (#1446).
      */
     private walkPageTiers;
+    /**
+     * Whether `username` is the page's author (#2097): `IdentityManager.refersTo`,
+     * so an author stored as an identity @id matches only its own account, one
+     * not yet converted matches its username, and an orphan matches nobody.
+     */
+    private isPageAuthor;
+    /** The username a page's stored author names (#2097), for the private-container fallback. */
+    private authorUsername;
     /**
      * The private-container decision for something that is not a page — a file
      * in a store (docs/private-stores.md, Access). The same rule a

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

@@ -1,6 +1,7 @@
 export interface PageComment {
     id: string;
     pageUuid: string;
+    /** Who wrote it: their identity `@id` (#2041); a username on a comment written before and not yet converted (a vault page's), or one with no account. */
     author: string;
     authorDisplayName: string;
     content: string;

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

@@ -5,9 +5,12 @@
  * org under `ngdpbase.application.organization.storagedir`. The install's
  * anchor org is identified by `ngdpbase.application.organization.file`.
  *
- * `@id` is the organization's canonical URL (e.g. https://example.com/),
- * NOT a synthetic urn. Use the schema.org `identifier` field for any
- * legacy slug compatibility.
+ * `@id` is a `urn:uuid:<v4>` made with the record, the organization's id for
+ * life (#2041, identity model step 6). Its web address is the ordinary `url`
+ * field, never the id. Organizations made before #2041 keep the `@id` they
+ * were given (often their URL); nothing refers to an organization by URL as
+ * its id from then on. Use the schema.org `identifier` field for any legacy
+ * slug compatibility.
  *
  * @see https://schema.org/Organization
  */
@@ -61,13 +64,13 @@ export type ContactPointEntry = ContactPoint | PostalAddress;
 export interface Organization {
     '@context': 'https://schema.org';
     '@type': 'Organization';
-    /** Canonical URL of the organization (the JSON-LD subject IRI) */
+    /** The organization's id for life: `urn:uuid:<v4>` (#2041); an organization made before #2041 keeps its own, often its URL */
     '@id': string;
     /** Human-readable name */
     name: string;
     /** Legal/registered name if different from `name` */
     legalName?: string;
-    /** Public web URL — usually the same as `@id` */
+    /** Public web address: an ordinary field, never the id (#2041) */
     url?: string;
     /** Logo URL */
     logo?: string;
@@ -87,10 +90,10 @@ export interface Organization {
     [key: string]: unknown;
 }
 /**
- * What a caller gives `OrganizationManager.create` (#1930): the fields, with
- * `@id` optional (it defaults to the `url`, else a new `urn:uuid:`).
+ * What a caller gives `OrganizationManager.create` (#1930): the fields. The
+ * `@id` is never the caller's: `create` makes a new `urn:uuid:` (#2041).
  */
-export type OrganizationInput = Partial<Organization> & {
+export type OrganizationInput = Partial<Omit<Organization, '@id'>> & {
     name: string;
 };
 /**

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

@@ -107,6 +107,12 @@ export interface GetPagesByCreatorOptions {
      * failure mode). Frontmatter is the source of truth and needs no back-fill.
      */
     systemKeywords?: string[];
+    /**
+     * The stored values that name the user (#2097): their identity @id and,
+     * for pages not yet converted, their username (`IdentityManager.referencesOf`).
+     * Set by PageManager; a provider compares `author` against these. Default `[username]`.
+     */
+    references?: string[];
 }
 /**
  * Options for {@link PageProvider.getPagesByEditor} / {@link PageProvider.getPagesSharedWith} (#640 Phase 2).
@@ -116,6 +122,12 @@ export interface PagesScanOptions {
     limit?: number;
     /** Sort order. Default `lastModified-desc`. */
     sortBy?: 'lastModified-desc' | 'title-asc';
+    /**
+     * The stored values that name the user (#2097), as {@link GetPagesByCreatorOptions.references}:
+     * `getPagesByEditor` compares `editor` against them, `getPagesSharedWith` leaves out pages
+     * whose `author` is one of them. Set by PageManager.
+     */
+    references?: string[];
 }
 /**
  * Single entry returned by {@link PageProvider.getRecentChanges}.
@@ -362,8 +374,8 @@ export interface PageProvider extends BaseProvider {
     /**
      * Return pages owned by the given user (#640).
      *
-     * "Owned" matches by `author` or `creator` field — pageIndex keeps these in
-     * lockstep on save. The visibility filter is intentionally NOT applied here
+     * "Owned" matches by `author` (any of `options.references`, #2097) or, on a
+     * private page, by `creator`, its container owner's username. The visibility filter is intentionally NOT applied here
      * because by definition a user can see their own pages: the route handler
      * verifies that `username === currentUser.username` before calling this.
      *

package/lib/src/utils/auditEvents.d.ts

@@ -126,8 +126,10 @@ export interface TokenInput extends CommonInput {
     op: TokenOp;
     /** Token id — the handle every later question about this credential uses. */
     id: string;
-    /** Whose token it is, which is not always who acted: an admin may revoke. */
+    /** Whose token it is, which is not always who acted (an admin may revoke): their identity @id (#2041), or a name with no account as given. */
     owner: string;
+    /** The token owner's username, written beside `owner` (#2041) so the rows still list after the account is deleted. */
+    ownerUser?: string;
     /** Operator-supplied label. Optional; a token need not be named. */
     name?: string | null;
     /** Only meaningful for `mint`; ignored otherwise. */
@@ -149,11 +151,14 @@ export type AttachmentDetail = {
     filename: string;
     pageName?: string | null;
     sizeBytes?: number | null;
-} | {
+}
+/** A sealed store's file: `owner` is the store owner's identity @id in the record, `ownerUser` their username beside it (#2041). */
+ | {
     attachmentId: string;
     sealedStore: {
         owner: string;
         store: string;
+        ownerUser?: string;
     };
 };
 export type AttachmentInput = CommonInput & {

package/lib/src/utils/auditEvents.js

@@ -148,7 +148,7 @@ export function buildAttachmentAuditEvent(input) {
     const { op, attachmentId, viaToken } = input;
     const who = whoOf(input);
     const metadata = 'sealedStore' in input
-        ? { attachmentId, owner: input.sealedStore.owner, store: input.sealedStore.store, sealed: true, ...tokenMetadata(viaToken), ...who.metadata }
+        ? { attachmentId, owner: input.sealedStore.owner, ...(input.sealedStore.ownerUser ? { ownerUser: input.sealedStore.ownerUser } : {}), store: input.sealedStore.store, sealed: true, ...tokenMetadata(viaToken), ...who.metadata }
         : { attachmentId, filename: input.filename, ...tokenMetadata(viaToken), ...who.metadata };
     if (!('sealedStore' in input)) {
         if (input.pageName)
@@ -273,11 +273,12 @@ export async function recordAuditEvent(sink, event, onError) {
  * every event is useless as a filter.
  */
 export function buildTokenAuditEvent(input) {
-    const { op, id, owner, name, scopes, expiresAt, previousExpiresAt, revokedBy, viaToken } = input;
+    const { op, id, owner, ownerUser, name, scopes, expiresAt, previousExpiresAt, revokedBy, viaToken } = input;
     const who = whoOf(input);
     const metadata = {
         id,
         owner,
+        ...(ownerUser ? { ownerUser } : {}),
         name: name ?? null,
         ...tokenMetadata(viaToken),
         ...who.metadata

package/lib/src/utils/identityStoreUnavailable.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The identity store could not answer a conversion's lookup (#2097).
+ *
+ * A start-up conversion tells this apart from every other failure: this one
+ * postpones the whole pass (no username is orphaned because it could not be
+ * looked up), while a page that fails for its own reason (a file it cannot
+ * read or write, a full disk, a vault it cannot open) is skipped, counted and
+ * the pass goes on. `IdentityManager.conversionPass` throws it; the providers
+ * and managers running a pass rethrow it and catch anything else per record.
+ */
+export declare class IdentityStoreUnavailableError extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * How a failure is named in a counts-only report: its error code (`EACCES`,
+ * `ENOSPC`) or class name, never its message (which may hold a path or a
+ * name).
+ */
+export declare function errorClassOf(error: unknown): string;

package/lib/src/utils/username.d.ts

@@ -55,5 +55,36 @@ export declare const RESERVED_USERNAMES: readonly string[];
  * identifier can never be, or later become, someone's username.
  */
 export declare const ACCOUNTLESS_PERSON_PREFIX = "person:";
-/** True when the name belongs to a principal rather than a person, or has the account-less person prefix. */
+/**
+ * The prefix of an identity's `@id` (#2041): `urn:uuid:<v4>`, and older
+ * organizations' `urn:…` ids. No username may start with it, so a stored
+ * reference is always told apart: a value starting `urn:` is an `@id`,
+ * anything else a username not yet converted.
+ */
+export declare const IDENTITY_ID_PREFIX = "urn:";
+/**
+ * The prefix a start-up conversion gives a stored username that has no
+ * account (#2041): `orphan:<name>`. The record is then nobody's: a later
+ * account with the same name never takes it over, no "is it mine" check
+ * matches it, and only an administrator can act on it. No username may
+ * start with it.
+ */
+export declare const ORPHAN_PREFIX = "orphan:";
+/**
+ * Values older records hold where no user was recorded (#2096, #2097): the
+ * footnote migration's `migrated`, the editor fallback `unknown` (and the
+ * attachment pool's `Unknown`), the JSPWiki import's `import`. Never a
+ * username: a start-up conversion never looks them up (an account that later
+ * takes one of these names must not gain the records), stores them as
+ * `orphan:<value>` and does not count them as needing attention.
+ */
+export declare const NO_RECORDED_USER: readonly string[];
+/** True when `value` is one of {@link NO_RECORDED_USER}, bare or as its orphan form. */
+export declare function isNoRecordedUser(value: unknown): boolean;
+/**
+ * True when the name belongs to a principal rather than a user, is a "no user
+ * recorded" value ({@link NO_RECORDED_USER}, #2097: an account by that name
+ * would take over the records that hold it), or has the contact, `@id` or
+ * orphan prefix.
+ */
 export declare function isReservedUsername(username: unknown): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.33.0",
+  "version": "5.35.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",