@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,1645 @@
+import { type DeclinedShippedPage } from '../utils/seededShippedPages.js';
+import BaseManager, { BackupData, type ManagerStats } from './BaseManager.js';
+import { WikiEngine } from '../types/WikiEngine.js';
+import { PageProvider, RecentChangesOptions, RecentChangeEntry, GetPagesByCreatorOptions, PagesScanOptions, StoreDeletedEntry, StoreRestoreResult } from '../types/Provider.js';
+import { WikiPage, PageFrontmatter } from '../types/Page.js';
+import type { VersionContent, VersionDiff, VersionHistoryEntry } from '../types/Version.js';
+import type { PermissionSubject } from './UserManager.js';
+import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, RebuildOpts, SchemaType } from '../types/Schema.js';
+import { type PageMutationOp } from '../utils/auditEvents.js';
+import { type FixChange, type FixResult, type RunFixesOptions } from '../converters/ncm/fix/index.js';
+import { type NcmResult } from '../converters/ncm/index.js';
+import type { FilterValidationError } from '../parsers/filters/FilterChain.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { type StoreSearchMatch, type StoreSearchQuery } from '../utils/storeSearchIndex.js';
+import { type Takeout } from '../utils/privateStoreExport.js';
+/**
+ * A save refused because the content broke a filter rule (#1037).
+ *
+ * Carries the structured violations so a route can answer with the same
+ * `400 { validationErrors }` shape the editor already understands, rather
+ * than degrading to a generic 500.
+ */
+/**
+ * Options for the page write methods (#1037).
+ */
+export interface PageSaveOptions {
+    /**
+     * Skip content validation. For content the instance ships ITSELF — addon
+     * page seeding, required-pages sync, generated profile pages. Never for
+     * anything a user supplied.
+     */
+    skipValidation?: boolean;
+    /** Attributed to the validation log line; purely diagnostic. */
+    userName?: string;
+    /**
+     * Skip the uniqueness check (#510) for a write whose whole purpose is to
+     * repair what that check refuses: the admin raw editor (#689) exists to fix
+     * duplicate slugs and duplicate uuids, and the gate would block the very
+     * edit being attempted. Never for an ordinary save.
+     */
+    skipConflictCheck?: boolean;
+    /**
+     * Write the frontmatter EXACTLY as given — no sanitisation (#296), no
+     * author/editor stamping (#1354), no provenance (#946), no former titles
+     * (#1105), no keyword, status or privacy normalisation (#893, #915, #639).
+     *
+     * For the admin raw editor (#689) and nothing else: there the textarea IS
+     * the page's bytes, and the admin is repairing frontmatter the normal path
+     * would rewrite — corrupt YAML, a duplicate slug, a stale uuid. Stamping
+     * the admin as `editor` would also be wrong: they are fixing a file, not
+     * authoring a revision, and the audit log is where that act is recorded.
+     *
+     * It also lifts the inline ACL-markup refusal, because a page still
+     * carrying legacy `[{ALLOW}]` markup is one of the things the raw editor
+     * exists to repair.
+     */
+    rawFrontmatter?: boolean;
+    /**
+     * The private name the page is at now, when this save moves it into
+     * another of its owner's vaults (#1505). Set by {@link PageManager.movePageToVault};
+     * the page, its history and its index entries go with it.
+     */
+    moveFrom?: string;
+    /**
+     * Rewrite a title that breaks the title rule (#1455) instead of refusing
+     * the page: the forbidden characters become `-`, the page records what its
+     * source called it in `alternateName`, and the result says so in
+     * `normalisedTitleFrom` for the caller's report.
+     *
+     * For the NCM funnel — import, MCP, paste, ingest — which converts data
+     * somebody else wrote, where refusing would drop a page from a bulk import
+     * over one character (operator, 2026-09-23). The editor never passes it: a
+     * person typing a title can simply be told.
+     */
+    normaliseTitle?: boolean;
+    /**
+     * Keep the page's `lastModified` from the metadata passed in. For a write
+     * that changes no content a reader cares about — e.g. stamping a shipped
+     * page's source hash (#1408) — so the page does not jump to the top of
+     * Recent Changes.
+     */
+    preserveLastModified?: boolean;
+    /**
+     * Keep the page's stored `editor` — who is recorded as having written this
+     * version — instead of taking it from the acting context (#1354).
+     *
+     * For the one-time private-link migration (#1457), and said to be that:
+     * rewriting `[Title]` to `[store/Title]` changes the syntax of a link, not
+     * what anybody wrote, so the last person to edit the page is still the last
+     * person to edit it. Stamping the system principal (at boot) or the owner
+     * (at unlock) over their name would be a claim about authorship that the
+     * migration has no business making. The act itself is in the audit trail,
+     * as `link-rewrite`, where it belongs.
+     *
+     * NOT `rawFrontmatter` (#689): that is the admin raw editor's, it lifts
+     * every rule in `normalizeSaveMetadata` rather than this one, and its own
+     * doc says so.
+     */
+    preserveEditor?: boolean;
+    /**
+     * Request-level detail the manager cannot see, for the audit record (#1121).
+     *
+     * The event is emitted by the manager either way — a caller that omits this
+     * still gets audited, which is the whole point of auditing at the door. This
+     * only ENRICHES the record with what lives on the HTTP request (the client
+     * IP) or with a semantic the manager cannot infer (a link-rewrite looks
+     * exactly like an ordinary edit from inside PageManager).
+     */
+    audit?: {
+        /**
+         * Override the derived op. Only `link-rewrite` needs this: create, edit
+         * and rename are all derivable here from the existing page and the
+         * incoming title, so a caller that passes nothing still gets them right.
+         */
+        op?: PageMutationOp;
+        /** Client IP, when the write arrived over HTTP. */
+        ipAddress?: string;
+        /** The rename that caused a `link-rewrite`. Ignored for other ops. */
+        rewriteOf?: {
+            from: string;
+            to: string;
+        } | null;
+        /**
+         * Suppress the event. For writes that are a side effect of an already
+         * audited operation, where a second record would describe the same act
+         * twice.
+         */
+        skip?: boolean;
+    };
+}
+/** What {@link PageManager.savePage} wrote. */
+export interface PageSaveResult {
+    /** The body as saved — always the caller's text: a save never rewrites it (#1332). */
+    content: string;
+    /** Where the page landed (#1462): its title, or its private path (#1456). */
+    name: string;
+    uuid: string;
+    /** The name it had before this save; null for a new page. */
+    previousName: string | null;
+    /** Pages that linked to the old name, read before a rename took it out of the link graph (#1094). */
+    previousReferrers: string[];
+    /**
+     * What the source called this page, when `normaliseTitle` rewrote a title
+     * that broke the rule (#1455). Null when nothing was rewritten. A funnel
+     * names it in its report — a page whose title changed under the reader's
+     * feet is a fact they are owed.
+     */
+    normalisedTitleFrom: string | null;
+}
+/**
+ * Why a deciding page read handed back nothing (#1622).
+ *
+ * - `not-found` — no such page for this caller (a sealed page this session
+ *   cannot unlock reads the same way).
+ * - `no-metadata` — the page exists but its metadata cannot be read, so
+ *   nothing can be decided about it: damage, refused (#1431 step 7d).
+ * - `denied` — the caller may not read it.
+ *
+ * A caller that answers a person who may not see the page should answer all
+ * three alike, so a refusal does not tell them the page exists.
+ */
+/**
+ * A site-chrome slot: a page that frames every page (#952, #950, #1622).
+ * `configKey` names the page; `legacy` is the deprecated slug-convention
+ * chain tried when the key is empty; `defaultPage` is used when the key is
+ * unset; `quiet` slots are optional, so a missing page is not reported.
+ */
+export type ChromeSlot = 'left-menu' | 'footer' | 'page-tabs';
+export type PageReadRefusal = 'not-found' | 'no-metadata' | 'denied';
+/**
+ * The answer of a deciding page read (#1622): the value, with the name and
+ * metadata the `page-read` decision was made on, or why there is none.
+ */
+export type PageRead<T> = {
+    ok: true;
+    name: string;
+    metadata: PageFrontmatter;
+    value: T;
+} | {
+    ok: false;
+    refusal: PageReadRefusal;
+};
+/** {@link PageManager.convertPageToNcm}: the NCM result plus the fix steps that changed the body. */
+export interface PageConvertResult extends NcmResult {
+    fixes: FixChange[];
+}
+export declare class PageContentValidationError extends Error {
+    readonly validationErrors: FilterValidationError[];
+    constructor(pageName: string, validationErrors: FilterValidationError[]);
+}
+/** One vault page with data outside its vault (#1842), as the repair actions offer it. */
+export interface VaultRepairItem {
+    owner: string;
+    vault: string;
+    /** The page's uuid; null for the pages of this vault that shared-pool records name. */
+    page: string | null;
+    /** Shared-pool files it uses. */
+    files: number;
+    /** Footnotes in the public folder. */
+    footnotes: boolean;
+    /** Comments in the public folder. */
+    comments: boolean;
+    /** Whether the asking context may repair it here. */
+    may: boolean;
+    /** Why not, in plain words. */
+    refusal?: string;
+    /**
+     * The vault page(s) as their reader sees them — title, link and the outside
+     * files by name — only when asked for (`listVaultRepairs(ctx, { details })`)
+     * and only those `ctx` may read; absent otherwise. Shown, never logged or
+     * recorded.
+     */
+    pages?: VaultRepairPage[];
+}
+/** One vault page of a repair item, for the reader of that page only (#1842). */
+export interface VaultRepairPage {
+    title: string;
+    /** The page's view URL. */
+    href: string;
+    /** Its shared-pool files, by name, with the URL that serves each today. */
+    files: Array<{
+        name: string;
+        href: string;
+    }>;
+}
+/** What one repair moved (#1842). */
+export interface VaultRepairCounts {
+    /** Shared-pool files moved in, no public copy left. */
+    filesMoved: number;
+    /** Shared-pool files copied in, the public copy left for the other pages that use it. */
+    filesCopied: number;
+    footnotes: number;
+    /** Comment files. */
+    comments: number;
+}
+export type VaultRepairRefusal = 'not-found' | 'vault-not-open' | 'denied' | 'locked' | 'owner-only';
+export type VaultRepairResult = ({
+    ok: true;
+    as: 'owner' | 'admin';
+} & VaultRepairCounts) | {
+    ok: false;
+    refusal: VaultRepairRefusal;
+    message: string;
+};
+/** The move of existing captures into the capture vault (#1505), recorded per vault it moved them out of. */
+export declare const CAPTURE_VAULT_MIGRATION = "capture-vault";
+/** The move of private pages from the default vault into their system-category's own vault (#1507). */
+export declare const CATEGORY_VAULT_MIGRATION = "category-vaults";
+/** Private slugs from `private--…` to `vaults--…` (#1507). */
+export declare const VAULT_SLUG_MIGRATION = "vault-slugs";
+/**
+ * Minimal WikiContext interface for type safety
+ * TODO: Convert WikiContext.js to TypeScript and import proper type
+ */
+interface WikiContext {
+    pageName: string;
+    content: string;
+    userContext?: {
+        username?: string;
+    };
+}
+/**
+ * A folder of pages ngdpbase ships, for `PageManager.seedShippedPages` (#1405).
+ */
+export interface ShippedPageSource {
+    /** Key in the site's seeded-pages record: `required-pages`, or `addon:<name>` */
+    id: string;
+    /** For log lines */
+    label: string;
+    /** Folder of `.md` source pages */
+    dir: string;
+    /** Frontmatter key for the stamped body hash (`required-source-hash`, `addon-source-hash`) */
+    stampKey: string;
+    /** Reason to never seed a page, or undefined to seed it */
+    exclude?: (data: Record<string, unknown>) => string | undefined;
+    /** Metadata the source adds to every page it writes (e.g. `addon`, a default category) */
+    extraMetadata?: (data: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Called by the boot seed for a source page this site already holds, with the
+     * live page and the parsed source — the addon seed's metadata tidy-ups and
+     * opt-in reseed (#971, #1003, #920). Not called for removed or trashed pages.
+     */
+    onPresent?: (live: WikiPage, source: {
+        data: Record<string, unknown>;
+        content: string;
+    }, ctx: ActorContext) => Promise<void>;
+}
+/** Why a shipped page was not seeded. */
+export type ShippedPageFailureCode = 'missing-or-invalid-uuid' | 'missing-title' | 'missing-slug' | 'duplicate-uuid' | 'save-failed';
+/** What `seedShippedPages` did with each source page. */
+export interface ShippedPageSeedReport {
+    /** Titles saved as new pages */
+    seeded: string[];
+    /** Source pages already live */
+    present: number;
+    /** Titles seeded here before (or trashed) and no longer live — left removed */
+    removed: string[];
+    /** Pages the source excludes */
+    excluded: Array<{
+        file: string;
+        title: string;
+        reason: string;
+    }>;
+    /** Pages that could not be seeded, with why */
+    failed: Array<{
+        file: string;
+        title: string;
+        reason: string;
+        code: ShippedPageFailureCode;
+    }>;
+    /** True when this run started the site's record for the source */
+    recordStarted: boolean;
+    /** Titles of live pages that had no stamp and matched the source, now stamped (#1408) */
+    stamped: string[];
+    /** Titles of live pages with no stamp whose body differs from the source — left unstamped (#1408) */
+    unstamped: string[];
+    /** Titles this site declined from the source — never seeded, never reported as a failure (#1412) */
+    declined: string[];
+}
+/** What `syncShippedPages` did with each requested uuid. */
+export interface ShippedPageSyncReport {
+    /** Uuids saved from the source */
+    synced: string[];
+    /** Uuids left alone because the live page was edited on this site */
+    protected: string[];
+    /** Uuids the source does not ship */
+    missing: string[];
+    /** Uuids that could not be saved, with why */
+    failed: Array<{
+        uuid: string;
+        reason: string;
+    }>;
+}
+/**
+ * PageManager - Manages wiki page operations through a pluggable provider system
+ *
+ * Follows JSPWiki's provider pattern where the actual storage implementation
+ * is abstracted behind a provider interface. This allows for different storage
+ * backends (filesystem, database, cloud, etc.) to be swapped via configuration.
+ *
+ * The PageManager acts as a thin coordinator that:
+ * - Loads the configured provider (via "ngdpbase.page.provider")
+ * - Proxies all page operations to the provider
+ * - Maintains the public API for backward compatibility
+ *
+ * @class PageManager
+ * @extends BaseManager
+ *
+ * @property {PageProvider|null} provider - The active page storage provider
+ * @property {string} providerClass - The class name of the loaded provider
+ *
+ * @see {@link BaseManager} for base functionality
+ * @see {@link FileSystemProvider} for default provider implementation
+ *
+ * @example
+ * const pageManager = engine.getManager('PageManager');
+ * const page = await pageManager.getPage('Main');
+ * console.log(page.content);
+ */
+declare class PageManager extends BaseManager implements CatalogSource {
+    /** CatalogSource identifier (Slice 4 of #755 / #772). */
+    readonly sourceId = "pages";
+    /**
+     * Subtypes this source produces. Pages always map to Article (Decision 1).
+     * Very-sparse pre-#754 pages still produce Article — `dateCreated` is the
+     * only Article-distinctive field and it's now mandatory after the
+     * #754 backfill (v3.33.0).
+     */
+    readonly types: readonly SchemaType[];
+    /**
+     * On-disk schema version for the page-frontmatter shape (Decision 6).
+     * Bump when the persisted Article-relevant fields on a page change. v1 is
+     * the post-#754 (v3.33.0) shape, which adds the required `created`
+     * timestamp to every page.
+     */
+    static readonly CURRENT_SCHEMA_VERSION = 1;
+    readonly currentSchemaVersion = 1;
+    private provider;
+    /**
+     * Lowercased former title → current title, or AMBIGUOUS (#1105).
+     *
+     * Null until first use. Built lazily rather than at boot: it is only ever
+     * consulted on the 404 path, so an instance that never serves a stale URL
+     * never pays for it. Invalidated on any save that changes `formerTitles`.
+     */
+    private formerTitleIndex;
+    private providerClass?;
+    /**
+     * Creates a new PageManager instance
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the PageManager by loading and initializing the configured provider
+     *
+     * Reads the page provider configuration and dynamically loads the provider class.
+     * The provider name is normalized from lowercase (config) to PascalCase (class name).
+     *
+     * @async
+     * @param {Object} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     * @throws {Error} If ConfigurationManager is not available or provider fails to load
+     *
+     * @example
+     * await pageManager.initialize();
+     * // Loads FileSystemProvider by default
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Startup check (#1834): every vault of a sealed kind whose files are in the
+     * clear — written before its door was opened, or under a `store.json` that
+     * is not sealed. Such a vault is closed (its store I/O refuses it); this
+     * makes it visible: an error in the log, the degraded-subsystem banner and a
+     * system notification, each naming owner and vault. Nothing is moved, sealed
+     * or deleted; an administrator decides what to do with the files.
+     */
+    private reportUnsealedVaults;
+    /**
+     * Convert a single page (frontmatter + name) to its schema.org `Article`
+     * record. Public so view-page / API consumers can build the same shape
+     * without rerouting through `CatalogManager`.
+     *
+     * The render mapper for the `<script type="application/ld+json">` block on
+     * `view.ejs` is a separate utility (`src/utils/buildPageJsonLd.ts`) — it
+     * adds `@context` and a couple of JSON-LD-render conventions on top of this
+     * internal record. Per `docs/schemas.md` Decision 11.
+     */
+    toCreativeWork(pageName: string, metadata: PageFrontmatter | null | undefined, options?: {
+        baseUrl?: string;
+        autoTaggedKeywords?: string[];
+    }): CreativeWork;
+    /**
+     * CatalogSource.get — fetch a single page by UUID and return its `Article`.
+     *
+     * Returns null for unknown UUIDs. ACL filtering is **not** applied here —
+     * callers needing the full WikiContext path should go through `getPage()`.
+     * (Same convention as `MediaManager.get` / `AttachmentManager.get`.)
+     */
+    get(identifier: string): Promise<CreativeWork | null>;
+    /**
+     * CatalogSource.list — paginated list of CreativeWorks across all pages.
+     *
+     * Initial implementation: pulls `getAllPageInfo()`, applies text / keyword
+     * / type / dateRange filters in-process, returns up to `query.limit`
+     * items. Cursor pagination is not implemented yet — the existing
+     * search-provider path (Lunr / ES) is the production query surface;
+     * this method exists so cross-source CatalogManager fan-out works.
+     */
+    list(query: CatalogQuery): Promise<CatalogPage>;
+    /**
+     * CatalogSource.rebuild — re-scan storage and rebuild the page-index. Wraps
+     * `provider.refreshPageList()`. The `force` option is accepted for
+     * `RebuildOpts` compatibility but doesn't change behavior — the underlying
+     * provider always does a full rescan.
+     */
+    rebuild(_opts?: RebuildOpts): Promise<void>;
+    /**
+     * Seed the pages a source ships into this site (#1405, epic #1404).
+     *
+     * The one place shipped pages are seeded. For each source page, in order:
+     *
+     * - no valid uuid, no title or no slug: skipped and reported
+     * - a uuid already used by another file of the same source: skipped and reported
+     * - excluded by the source (e.g. github-only categories): skipped
+     * - **in this site's seeded record**: never seeded again. If it is no longer
+     *   live it was removed here, and it stays removed.
+     * - live already: added to the record
+     * - in the trash: added to the record and skipped (#1403)
+     * - otherwise: saved through `savePage` with the source's stamp, indexed for
+     *   search, and added to the record
+     *
+     * A save the ValidationManager refuses (a title or slug held by another uuid)
+     * is reported, not retried; Required Pages Sync shows it as a UUID mismatch.
+     *
+     * A source this site has no record for yet starts it from the uuids that are
+     * live or in the trash, so an established site does not treat its shipped
+     * pages as new.
+     *
+     * @param source - Where the pages come from and how they are stamped
+     * @param ctx - Who seeds; a boot job's system context
+     * @returns What happened to each source page
+     */
+    seedShippedPages(source: ShippedPageSource, ctx: ActorContext): Promise<ShippedPageSeedReport>;
+    /**
+     * Save the source's copy of the given uuids as this site's pages (#1406) —
+     * the explicit sync behind Admin → Required Pages Sync.
+     *
+     * Unlike the boot seed this overwrites a live page, and it ignores the
+     * seeded-pages record: an admin's Sync is how a page removed on the site is
+     * brought back. Without `force`, a live page edited on this site (the
+     * `user-modified` flag, or a body that no longer matches its stamp) is left
+     * alone and reported as protected.
+     *
+     * A live page under another title is saved under that title, with the
+     * source title in the metadata — a rename, not a second page (#1376).
+     *
+     * @param source - Where the pages come from and how they are stamped
+     * @param uuids - Pages to sync
+     * @param options - `force` overwrites pages edited on this site
+     * @param ctx - Who asked
+     * @returns What happened to each uuid
+     */
+    syncShippedPages(source: ShippedPageSource, uuids: string[], options: {
+        force?: boolean;
+    }, ctx: ActorContext): Promise<ShippedPageSyncReport>;
+    /**
+     * Record that this site will not take a shipped page from a source (#1412).
+     *
+     * For a page whose title or slug belongs to a page the site would rather
+     * keep: the seeder skips it from then on, so the conflict stops being
+     * reported at every start-up. Nothing is written to any page, and the entry
+     * is per source — an addon shipping the same uuid is still offered.
+     *
+     * @param sourceId - `required-pages`, or `addon:<name>`
+     * @param uuid - The shipped page's uuid
+     * @param reason - The conflict that prompted it
+     * @param ctx - Who decided
+     * @returns True when it was not already declined
+     */
+    declineShippedPage(sourceId: string, uuid: string, reason: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Undo a decline (#1412), so the page is offered again at the next start-up
+     * or Sync.
+     *
+     * @param sourceId - `required-pages`, or `addon:<name>`
+     * @param uuid - The shipped page's uuid
+     * @param ctx - Who decided
+     * @returns True when there was a decline to undo
+     */
+    allowShippedPage(sourceId: string, uuid: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Every shipped page this site has declined, as source id → uuid → entry
+     * (#1412). Read by Required Pages Sync to list them.
+     */
+    declinedShippedPages(): Promise<Record<string, Record<string, DeclinedShippedPage>>>;
+    /** The site's seeded-pages record. */
+    private loadSeededRecord;
+    /**
+     * The source for the required pages this release ships (#1405, #1406).
+     * Pages in a category whose source is `repo` are excluded.
+     */
+    requiredPagesSource(): ShippedPageSource;
+    /**
+     * One-time access backfill for a live required page (#1411): a page with no
+     * `access` gets the default for its category, as a metadata-only save that
+     * keeps `lastModified`. A page that has any `access` — an operator's choice —
+     * is left alone.
+     */
+    private backfillShippedPageAccess;
+    /**
+     * The source for the pages an addon ships (#1406). Pages it writes carry
+     * `addon` and, when the source names none, the `addon` category (#931).
+     *
+     * @param addonName - The addon's name
+     * @param pagesDir - The addon's `pages/` folder
+     */
+    addonPagesSource(addonName: string, pagesDir: string): ShippedPageSource;
+    /**
+     * Stamp a live shipped page that has no stamp, when its body matches the
+     * source (#1408). Its hash then equals the source's, so the stamp records
+     * exactly what the site holds; without one, a later source change cannot be
+     * told from a local edit. A page whose body differs cannot be proven
+     * unedited and is left unstamped, reported for an admin.
+     *
+     * A metadata-only save: no version is written for the unchanged body
+     * (#1407), and `lastModified` is kept so Recent Changes stays quiet.
+     *
+     * @returns True when the page was stamped
+     */
+    private backfillShippedPageStamp;
+    /**
+     * This site's own copy of a shipped page, or null. A page served from the
+     * source folder is the source, not the site's page.
+     */
+    private storeCopyByUUID;
+    /**
+     * Write one shipped page through `savePage`, stamped, as the system
+     * principal, then index it for search. Throws when the save is refused.
+     */
+    private saveShippedPage;
+    /**
+     * Seed the required pages this release ships (#1405). Runs at the end of
+     * engine start-up, once ValidationManager and SearchManager exist, so a
+     * seeded page gets the conflict check and search indexing a save gets.
+     *
+     * A required page is seeded once per site: pages new in a release appear at
+     * restart, and a page removed on the site stays removed (#954). Pages in a
+     * category whose source is `repo` are never seeded.
+     *
+     * Best-effort: a failure is logged and never blocks start-up.
+     */
+    seedRequiredPages(): Promise<void>;
+    /**
+     * Get provider information
+     * @private
+     */
+    private getProviderInfo;
+    /**
+     * Normalize provider name from configuration (lowercase) to class name (PascalCase)
+     * @param {string} providerName - Provider name from configuration (e.g., 'filesystemprovider')
+     * @returns {string} Normalized class name (e.g., 'FileSystemProvider')
+     * @private
+     */
+    private normalizeProviderName;
+    /**
+     * Get the current page provider instance
+     *
+     * @returns {PageProvider} The active provider instance
+     *
+     * @example
+     * const provider = pageManager.getCurrentPageProvider();
+     * const info = provider.getProviderInfo();
+     * console.log('Using:', info.name);
+     */
+    getCurrentPageProvider(): PageProvider | null;
+    getPageUUID(identifier: string, ctx: ActorContext): string | null;
+    /**
+     * Evict a page's cached content, and bump the page-data version so every
+     * cached render re-renders (#1751).
+     */
+    invalidatePageCache(identifier: string): string | null;
+    /**
+     * Get complete page with content and metadata
+     *
+     * Retrieves a page by UUID, title, or slug. Returns the full page object
+     * including content, metadata, and file path information.
+     *
+     * @async
+     * @param {string} identifier - Page UUID, title, or slug
+     * @returns {Promise<WikiPage|null>} Page object or null if not found
+     *
+     * @example
+     * const page = await pageManager.getPage('Main');
+     * console.log(page.title, page.metadata.author);
+     */
+    getPage(identifier: string, ctx: ActorContext): Promise<WikiPage | null>;
+    /**
+     * The page in a site-chrome slot — the left menu, the footer, the page-tabs
+     * template — read the same way for every caller (#952, #950, #1622).
+     *
+     * Resolution order (#952):
+     *   1. The configured page, when the slot's key is set. Authoritative: if
+     *      that page is missing, the legacy chain is NOT tried, because silently
+     *      substituting a page the operator did not choose is the problem the
+     *      setting exists to remove.
+     *   2. Otherwise the legacy slug chain (`left-menu-content` before
+     *      `LeftMenu`), logged at info when a page shadows the core one.
+     *
+     * Chrome is read as the anonymous reader, for every viewer: it frames every
+     * page for everyone, and gating a fragment only ever removed navigation
+     * site-wide without protecting the pages it links to (#950). A restriction
+     * set on a chrome page is therefore reported, not enforced. This is not a
+     * person's page view, so it does not pass the page-read door; it is the one
+     * place chrome is read, which is what the door rule needs (#1622).
+     *
+     * @param slot - Which chrome page
+     * @returns The page, or null when none resolves
+     */
+    readChromePage(slot: ChromeSlot): Promise<WikiPage | null>;
+    /**
+     * Warn when a chrome page carries access control that is no longer honoured (#950).
+     *
+     * `LeftMenu` and `Footer` used to run the full ACL evaluator, and a denial
+     * replaced the fragment with an empty string — so an affected user lost the
+     * sidebar or footer on EVERY page of the site, with nothing logged above
+     * `info` and nothing pointing at permissions as the cause.
+     *
+     * That gating is removed. A fragment is never a destination: denying it
+     * protected nothing, because the pages it links to still enforce their own
+     * ACLs, and a link the user cannot follow returns a comprehensible 403.
+     *
+     * The failure mode of removing it is the mirror image — frontmatter that
+     * silently stops working — so a restriction on a chrome page is reported
+     * rather than dropped in silence. `private: true` is called out by name
+     * because it is a hard constraint everywhere else in the evaluator, and an
+     * operator who set it has the strongest expectation of enforcement.
+     *
+     * @param label - Chrome slot being rendered
+     * @param metadata - The chrome page's frontmatter, if a page was resolved
+     */
+    private warnOnChromeRestriction;
+    /**
+     * Get only page content (without metadata)
+     *
+     * More efficient than getPage() when only content is needed.
+     *
+     * @async
+     * @param {string} identifier - Page UUID, title, or slug
+     * @returns {Promise<string>} Markdown content
+     *
+     * @example
+     * const content = await pageManager.getPageContent('Main');
+     * console.log(content);
+     */
+    getPageContent(identifier: string, ctx: ActorContext): Promise<string>;
+    /**
+     * Get only page metadata (without content)
+     *
+     * More efficient than getPage() when only metadata is needed.
+     *
+     * @async
+     * @param {string} identifier - Page UUID, title, or slug
+     * @returns {Promise<PageFrontmatter|null>} Metadata object or null if not found
+     *
+     * @example
+     * const meta = await pageManager.getPageMetadata('Main');
+     * console.log('Author:', meta.author);
+     */
+    /**
+     * Resolve a former page title to the page that holds it now, or null (#1105).
+     *
+     * **Callers must have already failed live resolution.** This is a fallback, not
+     * a lookup: answering for a title that still exists would let a stale name
+     * shadow a real page. `viewPage` calls it only on the not-found path.
+     *
+     * Returns null on ambiguity rather than guessing. A confidently wrong redirect
+     * to a page that merely once shared a name is worse than the 404 it replaces —
+     * a 404 is visibly broken, and the wrong page is not.
+     *
+     * @param formerTitle - The title that failed to resolve
+     * @returns The current title of the page that was renamed from it, or null
+     */
+    resolveFormerTitle(formerTitle: string): Promise<string | null>;
+    /**
+     * Walk the page set and derive the former-title index.
+     *
+     * Metadata comes from the provider's already-loaded cache, so this is memory
+     * work rather than I/O. A page whose metadata cannot be read is skipped — a
+     * single unreadable page must not deny resolution for every other.
+     *
+     * @private
+     */
+    private buildFormerTitleIndexFromPages;
+    getPageMetadata(identifier: string, ctx: ActorContext): Promise<PageFrontmatter | null>;
+    /**
+     * May `ctx` read this page, and which page is it? The one `page-read`
+     * decision (#1622), made for every deciding read below.
+     *
+     * The identifier — uuid, slug, title or vault name — is resolved once, and
+     * the decision is made on the page it resolved to, by its canonical name.
+     * `key` is how the reads then reach that same page: a vault page by its
+     * vault name, any other by its uuid, so a read cannot land on a different
+     * page than the one decided about.
+     *
+     * The page decision itself is the PIP's (`canUserAccessPage`, `view`):
+     * delegation ceilings, private, audience, policy. Without a PIP nothing is
+     * readable — never the page by accident.
+     */
+    private decideRead;
+    /** The provider's version reads, or a throw when it keeps no history. */
+    private versionReads;
+    /**
+     * Would `ctx` be allowed to read this page — asked only to decide whether to
+     * SHOW something (`<wiki:If exists:Page>`), never before reading it (#1668).
+     * The same `page-read` decision as {@link readPage}, so the two agree; it
+     * reads no content and writes no audit record. A page `ctx` may not read
+     * answers false, as one that does not exist does.
+     *
+     * @param identifier - Page UUID, title, slug or vault name
+     * @param ctx - Whose question this is (#1179) — never defaulted
+     */
+    mayShowPage(identifier: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Read a page — content and metadata — as `ctx`, if `ctx` may read it (#1622).
+     *
+     * @param identifier - Page UUID, title, slug or vault name
+     * @param ctx - Whose read this is (#1179) — never defaulted
+     * @returns The page, with the name and metadata the decision was made on,
+     *   or why there is none
+     */
+    readPage(identifier: string, ctx: ActorContext): Promise<PageRead<WikiPage>>;
+    /**
+     * A page's version history, newest first, if `ctx` may read the page (#1622).
+     *
+     * @throws When the provider keeps no history, or the history cannot be read
+     */
+    readVersionHistory(identifier: string, ctx: ActorContext, limit?: number): Promise<PageRead<VersionHistoryEntry[]>>;
+    /**
+     * One past version of a page, if `ctx` may read the page (#1622).
+     *
+     * @throws When the provider keeps no history, or the version does not exist
+     */
+    readVersion(identifier: string, version: number, ctx: ActorContext): Promise<PageRead<VersionContent>>;
+    /**
+     * The difference between two versions of a page, if `ctx` may read the page (#1622).
+     *
+     * @throws When the provider keeps no history, or either version does not exist
+     */
+    readVersionDiff(identifier: string, fromVersion: number, toVersion: number, ctx: ActorContext): Promise<PageRead<VersionDiff>>;
+    /**
+     * Read the literal raw file content for a page — frontmatter YAML + body
+     * markdown together, exactly as it appears on disk. Backs the admin
+     * "Edit raw" UI (#689); intended for recovery of pages whose frontmatter
+     * the normal getPage() path sanitises or normalises away. Returns null
+     * when the page is unknown or the provider doesn't support raw reads.
+     */
+    getRawPageContent(identifier: string): Promise<{
+        filePath: string;
+        content: string;
+    } | null>;
+    /**
+     * Admin-override save (#689): the admin "Edit raw" textarea, split into
+     * frontmatter and body and written through the door (#1462).
+     *
+     * It goes through `savePage` like every other write — so it versions, keeps
+     * the shared indexes in step and is audited — with the three opt-outs that
+     * make raw editing what it is, stated at this one call site:
+     *
+     *   rawFrontmatter    the file's bytes are the point: no sanitisation, no
+     *                     stamping. The admin is repairing a file, not authoring
+     *                     a revision, so they do NOT become its `editor`.
+     *   skipConflictCheck a duplicate slug or uuid is what it was opened to fix.
+     *   skipValidation    so is content a filter rule refuses.
+     *
+     * The audit op is pinned to `edit`: the raw editor writes an existing file
+     * in place, and the identifier in its URL may be a uuid, so a difference
+     * between it and the frontmatter title is not a rename. The route adds its
+     * own `page.raw-edit` record, which carries what this one cannot — the
+     * admin override, the file path and the byte count.
+     *
+     * Throws if the textarea content isn't parseable YAML.
+     */
+    saveRawPageWithAdminOverride(pageName: string, rawFileContent: string, ctx: ActorContext): Promise<PageSaveResult>;
+    /**
+     * Refuse a save whose content breaks a filter rule (#1037).
+     *
+     * Lives here, not in the route handlers, because that is where it kept
+     * getting forgotten: `/save/:page` had the check, `POST /create` — the
+     * "Create New Page" item in the header — did not, and neither did
+     * `/api/page/ingest`. Every write path reaches PageManager, so putting the
+     * gate here means a new caller inherits it instead of having to remember.
+     *
+     * `skipValidation` is for TRUSTED content the instance ships itself —
+     * addon page seeding, required-pages sync, generated profile pages. Those
+     * run at startup, and a rule aimed at user input must never be able to stop
+     * the instance booting. It is an explicit opt-out precisely so that reading
+     * a call site tells you which kind of content it writes.
+     *
+     * A failure inside ValidationManager is NOT a failure to save: it already
+     * degrades to "no errors" internally, and this method must not turn an
+     * infrastructure problem into a refused edit.
+     *
+     * @throws PageContentValidationError when a filter reports severity 'error'
+     */
+    private assertContentPasses;
+    /**
+     * The frontmatter a save writes, from the frontmatter it was given (#1462).
+     *
+     * Everything a write must not be able to forget about metadata, in one
+     * place: author preservation and the editor of record (#1354), agent
+     * provenance (#946), former titles (#1105), the privacy and vocabulary
+     * rules (#639, #893, #915) and sanitisation (#296).
+     *
+     * Only the admin raw editor skips it (`rawFrontmatter`, #689): there the
+     * file's bytes are the point, and every rule here would rewrite them.
+     *
+     * @param pageName - The page being written: its title, or a private path
+     * @param metadata - The frontmatter as the caller gave it
+     * @param existingPage - The page as stored, or null when this save creates it
+     * @param actingUser - Who is writing this revision, from the context (#1164)
+     * @param viaToken - The agent token this write came through (#946), if any
+     * @param keepEditor - Leave the stored `editor` alone (`preserveEditor`, #1457)
+     * @returns The frontmatter to hand the provider
+     */
+    private normalizeSaveMetadata;
+    /**
+     * Save a page — the one door every write goes through (#1462 slice 2).
+     *
+     * Creates a page or updates one, and owns everything a write must not be
+     * able to forget: content validation (#1037), the ACL-markup refusal,
+     * author preservation and the editor of record (#1354), agent provenance
+     * (#946), former titles (#1105), the privacy and vocabulary rules (#639,
+     * #893, #915), metadata sanitisation (#296), the uniqueness check (#510),
+     * the shared indexes (#1462) and the audit event (#1121).
+     *
+     * `ctx` is mandatory and positional: the save acts as the caller's subject
+     * (#1179), a private-store write reaches that session's keys through it
+     * (#1382), and the audit record names it. A caller forwards the context it
+     * was given — a request's subject, or the job's for boot and scheduled
+     * work — and never invents one.
+     *
+     * @param pageName - The page to write: its title, or a private path (#1456)
+     * @param content - The body, written exactly as given — a save never rewrites it (#1332)
+     * @param metadata - Frontmatter; server-owned fields in it are discarded, not merged
+     * @param ctx - Who is acting (#1179)
+     * @param options - Validation and conflict-check opt-outs, `rawFrontmatter` (#689),
+     *   `preserveLastModified`, `preserveEditor` (#1457), audit enrichment
+     * @returns Where the page landed, and what it was called before
+     *
+     * @example
+     * await pageManager.savePage('New Page', '# Hello World', { 'user-keywords': ['tutorial'] }, req.userContext);
+     */
+    savePage(pageName: string, content: string, metadata: Partial<PageFrontmatter> | undefined, ctx: ActorContext, options?: PageSaveOptions): Promise<PageSaveResult>;
+    /**
+     * Put an old version's body back, as a new version (#1462 slice 3).
+     *
+     * A restore is a save: it writes the page. It used to call the provider's
+     * own `restoreVersion`, which saved underneath the door — no content
+     * validation, no uniqueness check, no audit record and no shared-index
+     * work, so a restored page kept the RESTORED body on disk while search, the
+     * link graph and the rendered cache still described the one it replaced.
+     * Here the version is read and the body goes back through `savePage`.
+     *
+     * Nothing is destroyed: the newer versions stay in the history, and the
+     * restore is simply the newest one.
+     *
+     * @param identifier - Page UUID, title or slug
+     * @param version - The version whose body to restore
+     * @param ctx - Who is acting (#1179); the restore is attributed to them
+     * @returns Where the page landed, and the version number this created
+     * @throws When the page, the version or the provider's history is missing
+     */
+    restoreVersion(identifier: string, version: number, ctx: ActorContext): Promise<PageSaveResult & {
+        version: number | null;
+    }>;
+    /**
+     * Bring a page back from the trash (#947), and back into the shared
+     * indexes (#1462 slice 3).
+     *
+     * The provider moves the file and its history back; a restore is then a
+     * save-shaped change — the page is there again, under its restored title —
+     * so the link graph, search, mentions, assets and the rendered cache are
+     * brought in step here, where every other write has them done. The route
+     * used to do a partial job of this itself (search and the link graph only).
+     *
+     * @param uuid - The trashed page's UUID
+     * @param ctx - Who is acting (#1179); the restored page is read as them
+     * @returns The provider's result, unchanged — `ok`, or why not
+     */
+    restoreDeletedPage(uuid: string, ctx: ActorContext): Promise<{
+        ok: true;
+        title: string;
+    } | {
+        ok: false;
+        reason: string;
+        detail?: string;
+    }>;
+    /**
+     * The requester's own deleted private pages, newest first (#1459).
+     *
+     * Only their own container, and only the stores this context can open: a
+     * sealed store that is still locked contributes nothing.
+     *
+     * @param ctx - Who is asking (#1179) — never rebuilt, never defaulted
+     */
+    /**
+     * A takeout of one of the requester's OWN private stores (#1387).
+     *
+     * The door is here rather than in a route because a route should not be
+     * working out where a store lives on disk. What comes back is decrypted and
+     * in memory, ready to be packed and streamed; nothing is written anywhere.
+     *
+     * Only the requester's own store: `mayActInPrivateContainer` decides, as
+     * everywhere else, on ownership or delegation and never on a role. A store
+     * that is encrypted and locked in this session THROWS rather than returning
+     * an empty takeout — an archive that downloads cleanly and cannot be read is
+     * the worst outcome available, since it is discovered long afterwards.
+     */
+    buildOwnStoreTakeout(ctx: ActorContext, options: {
+        store: string;
+        pagesOnly?: boolean;
+    }): Promise<Takeout>;
+    /**
+     * The current pages of one vault, as `ctx` may enter it (#1388): its owner,
+     * or a share link the owner issued that names this vault. Anyone else gets
+     * an empty list, the same as a vault with nothing in it. Whether each page
+     * may then be read is still the page door's answer.
+     */
+    listVaultPages(ctx: ActorContext, owner: string, vault: string): Promise<Array<{
+        name: string;
+        title: string;
+        uuid: string;
+    }>>;
+    /** The store ids the requester has of their own (#1387). */
+    listOwnStoreIds(ctx: ActorContext): Promise<string[]>;
+    listOwnDeletedPrivatePages(ctx: ActorContext): Promise<StoreDeletedEntry[]>;
+    /**
+     * Bring one of the requester's private pages back from its store's trash
+     * (#1459).
+     *
+     * The provider moves the file back and restores the store's page-index
+     * entry; the store's search index is rebuilt for that page here, through the
+     * same reconciliation every save and restore runs, so no index is left
+     * behind. The page's version history never moved, so it is simply there again.
+     *
+     * @param ctx - Who is restoring (#1179)
+     * @param store - Which of the requester's stores
+     * @param uuid - The trashed page's uuid
+     */
+    restoreOwnPrivatePage(ctx: ActorContext, store: string, uuid: string): Promise<StoreRestoreResult>;
+    /**
+     * Destroy one of the requester's trashed private pages for good (#1459):
+     * the file, its version history in the store, and the tombstone.
+     *
+     * @param ctx - Who is purging (#1179)
+     * @param store - Which of the requester's stores
+     * @param uuid - The trashed page's uuid
+     */
+    purgeOwnPrivatePage(ctx: ActorContext, store: string, uuid: string): Promise<boolean>;
+    /**
+     * Expire the requester's own private tombstones past the retention window
+     * (#1459), in their session.
+     *
+     * THE SPLIT, stated where it happens: the boot and hourly retention passes
+     * run under a job context, which holds no store key, so they reach the
+     * unencrypted stores only. A SEALED store can be opened by nobody but its
+     * owner, so its trash is expired here, right after an unlock — the same
+     * division as #1457's link migration and #1458's search-index build, and for
+     * the same reason.
+     *
+     * Best-effort: a failure is logged and never blocks the unlock.
+     *
+     * @param ctx - The owner's context, holding the unlocked store keys
+     */
+    purgeExpiredOwnPrivateTrash(ctx: ActorContext): Promise<number>;
+    /**
+     * Convert a stored page (frontmatter + body) to NCM, with every fix step
+     * (#1332) — the one implementation behind Convert to NCM, agent ingest and
+     * the MCP create/update tools.
+     *
+     * The fix steps run on the body first, then `normalizeExistingPageToNcm`
+     * (links, table up-convert, `ncmVersion`), so NCM's determinism stays owned
+     * in one place. Each step that changed something is also reported as a
+     * `converter-note` warning, so the existing preview and notification
+     * surfaces show it without knowing about steps.
+     *
+     * Pure: nothing is saved.
+     *
+     * @param raw - Full page text, YAML frontmatter and body
+     * @returns The NCM result and the fix steps that changed the body
+     */
+    convertPageToNcm(raw: string): PageConvertResult;
+    /**
+     * The NCM door's second half (#1486): the conversion steps that write.
+     *
+     * `convertPageToNcm` is pure — fix steps, links, tables, `ncmVersion` — so a
+     * caller can validate and check for a stale version before anything is
+     * written. This runs after those checks, and is the one place the funnel's
+     * side effects happen:
+     *
+     * - remote images become attachments of the page (AttachmentManager), when
+     *   `localizeImages` is set — interactive Convert to NCM only, today; the
+     *   agent and import paths leave remote images as links;
+     * - `[^id]: text` definitions move to the page's footnote list
+     *   (FootnoteManager), when the page has a uuid and footnotes are enabled.
+     *
+     * Import, ingest, MCP and Convert to NCM all come through here, so they
+     * cannot drift apart again. With `dryRun` nothing is stored: the preview
+     * shows what apply will do.
+     *
+     * @param content - The converted page text (with or without frontmatter)
+     * @param target - The page it belongs to: its name, and its uuid when known
+     * @param ctx - Who is acting; attachments and footnotes are theirs
+     * @param options - `dryRun`, `localizeImages`
+     * @returns The text to save, and a warning per thing done or refused
+     */
+    completeNcmConversion(content: string, target: {
+        pageName: string;
+        uuid?: string;
+    }, ctx: ActorContext, options?: {
+        dryRun?: boolean;
+        localizeImages?: boolean;
+    }): Promise<{
+        content: string;
+        warnings: string[];
+    }>;
+    /**
+     * Run the Markdown fix steps over a page body (#1332).
+     *
+     * The one entry point for rewriting page text, so Convert to NCM, ingest,
+     * import and migrations cannot disagree about what a page should become.
+     * Every step runs, in registry order; `steps` picks steps by id instead.
+     * An ordinary save never calls this.
+     *
+     * Pure: nothing is saved. The result lists what each step changed, so the
+     * caller can report it.
+     *
+     * @param content - Page body, without frontmatter
+     * @param options - `steps` by id; default every step
+     * @returns The fixed body and the changes, empty when nothing changed
+     *
+     * @example
+     * const { content, changes } = pageManager.normalizePageContent(body);
+     */
+    normalizePageContent(content: string, options?: RunFixesOptions): FixResult;
+    /**
+     * Delete a page — the one door every delete goes through (#1462 slice 3).
+     *
+     * There were two: this one and `deletePageWithContext`, which took a whole
+     * WikiContext to read two fields off it and, when the context carried no
+     * user, deleted as the anonymous subject — a caller that HAD a subject could
+     * lose it on the way in. The context is mandatory and positional here, as it
+     * is for a save.
+     *
+     * The delete is soft (#947): the page goes to the trash with its history,
+     * and the context names who put it there. Afterwards the page is taken out
+     * of every shared index, here and nowhere else (#1462).
+     *
+     * @param identifier - Page UUID, title, or slug
+     * @param ctx - Who is acting (#1179)
+     * @returns True if deleted, false if not found
+     *
+     * @example
+     * const deleted = await pageManager.deletePage('Old Page', req.userContext);
+     */
+    deletePage(identifier: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * 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
+     * slug.
+     */
+    private nameOf;
+    /**
+     * The shared indexes after a page changed (#1462) — the one place they are
+     * kept in step: the link graph, search, attachment mentions, page assets,
+     * and the rendered-page cache of the page and of the pages linking to it.
+     * A private page (#1456) is in none of them; a page that left the public
+     * space, or was deleted or renamed, is taken out under its old name.
+     *
+     * A failure here is logged, not thrown: the page is already saved, and the
+     * indexes are rebuilt by the reindex job. It is never silent.
+     *
+     * @returns the pages that linked to the old name, read before it left the
+     *   link graph — what a rename rewrites (#1094)
+     */
+    private reconcileSharedIndexes;
+    /** A private page's store's search index, after the page changed (#1458). */
+    private reconcileStoreSearch;
+    /**
+     * The requester's own private pages that match, from their stores' own
+     * search indexes (#1458).
+     *
+     * Only the requester's own container is read: `mayActInPrivateContainer` is
+     * the same rule the page gate applies, so no role reaches in and an admin
+     * searching finds nothing of anyone else's. A store whose key this context
+     * does not hold contributes nothing — a locked store simply yields no
+     * matches, never a plaintext read.
+     *
+     * Each match carries the page's private NAME (`private/{owner}/{store}/{title}`),
+     * so `pageUrl` builds a link that works.
+     *
+     * @param ctx - Who is searching (#1179) — never rebuilt, never defaulted
+     * @param ask - The query, as {@link matchStoreSearch} reads it
+     */
+    searchOwnPrivatePages(ctx: ActorContext, ask?: StoreSearchQuery): Promise<Array<StoreSearchMatch & {
+        name: string;
+        owner: string;
+        store: string;
+    }>>;
+    /**
+     * Build a store's search index from its pages, replacing whatever is there.
+     *
+     * The repair for a lost or stale index, and what a store with none gets at
+     * its first boot or unlock. The pages are read through this door with `ctx`,
+     * so a sealed store is read with the owner's key and nothing reads a store
+     * file from outside the provider.
+     *
+     * @param ctx - Whose reading and writing this is (#1179)
+     * @param owner - Whose store
+     * @param store - Which store
+     * @returns How many documents the index now holds
+     */
+    rebuildStoreSearchIndex(ctx: ActorContext, owner: string, store: string): Promise<number>;
+    /**
+     * Give every readable store that has no search index one, built from its
+     * pages (#1458).
+     *
+     * A store with an index is left alone, so this is cheap at every boot and
+     * every unlock; a store whose index was lost gets it back. That the file is
+     * missing IS the marker — unlike the link migration (#1457), which had to
+     * record that it ran because its result is indistinguishable from never
+     * having run, an absent index says plainly that one is needed.
+     *
+     * Only the stores `ctx` can open are visited: the system principal reaches
+     * the unencrypted ones at boot, the owner's own session reaches their sealed
+     * ones at unlock. One store's failure never stops the others.
+     *
+     * @param ctx - Whose reading and writing this is (#1179)
+     * @param owner - One user's stores, or every readable store when omitted
+     * @returns How many stores were given an index
+     */
+    buildMissingStoreSearchIndexes(ctx: ActorContext, owner?: string): Promise<number>;
+    /**
+     * Build the missing search indexes of the unencrypted stores, at boot.
+     *
+     * Best-effort: a failure is logged and never blocks start-up. An encrypted
+     * store is not readable here — it gets its index at its owner's unlock, the
+     * same split the link migration uses (#1457).
+     */
+    buildStoreSearchIndexesAtBoot(): Promise<void>;
+    /**
+     * Whether a page may go into an index that every reader of this process or
+     * its disk shares — the search index, the page-assets index, the link graph
+     * and the known-page-name list (#1419).
+     *
+     * Such an index is built as the anonymous subject (docs/planning/
+     * private-stores.md, Context): the question is asked with that subject
+     * stated, not with a default. A private page never qualifies (#1456): it
+     * is listed only in its own store's indexes, encrypted or not.
+     */
+    isSharedIndexable(identifier: string): boolean;
+    /**
+     * Check if page exists
+     *
+     * Fast existence check without loading page content.
+     *
+     * @param {string} identifier - Page UUID, title, or slug
+     * @returns {boolean} True if page exists
+     *
+     * @example
+     * if (pageManager.pageExists('Main')) {
+     *   console.log('Main page exists');
+     * }
+     */
+    pageExists(identifier: string, ctx: ActorContext): boolean;
+    /**
+     * The private titles `ctx` can see in `owner`'s stores, by store id (#1457).
+     *
+     * For the one question a `[store/Title]` link asks while a PRIVATE page is
+     * rendered: is that page there? A private page's HTML is never cached for
+     * sharing (`isSharedIndexable` is false for every private name), so its
+     * links may be answered for the reader in front of them.
+     *
+     * A store `ctx` cannot open is absent from the map, not empty: the caller
+     * must render "cannot say" as it renders for everyone, never as a missing
+     * page. Titles are folded to lower case, which is how a store index matches
+     * them, so a caller compares folded.
+     *
+     * @param owner - Whose stores
+     * @param ctx - Whose reading this is (#1179) — never rebuilt, never defaulted
+     */
+    readablePrivateTitles(owner: string, ctx: ActorContext): Promise<Map<string, Set<string>>>;
+    /**
+     * Whether a page uuid is in the trash (#1403).
+     *
+     * A seed of shipped pages must treat a trashed uuid as deliberately removed,
+     * not missing. `pageExists` sees live pages only. A provider without soft
+     * delete has no trash, so this is false there.
+     *
+     * @param uuid - Page UUID
+     * @param _ctx - Who is asking
+     * @returns True if the uuid has a trash entry
+     */
+    isPageDeleted(uuid: string, _ctx: ActorContext): boolean;
+    /**
+     * Get all page titles
+     *
+     * Returns a sorted list of all page titles in the wiki.
+     *
+     * @async
+     * @returns {Promise<string[]>} Sorted array of page titles
+     *
+     * @example
+     * const pages = await pageManager.getAllPages();
+     * console.log('Total pages:', pages.length);
+     */
+    getAllPages(): Promise<string[]>;
+    /**
+     * The pages `subject` may perform `action` on — the door for anything that
+     * lists pages to a reader (#1219, guiding-framework rule 10).
+     *
+     * A title is content: a private page named for what it holds discloses by
+     * appearing in a list. `getAllPages()` above is the unfiltered index and
+     * stays for callers with no reader — indexing, link graphs, jobs, and admin
+     * surfaces already gated by `admin-system`. Anything rendered to a request
+     * goes through here, so the listing and `canAccess` are the same evaluator
+     * (`PolicyInformationPoint.filterAccessiblePages`). Without an PolicyInformationPoint nothing is
+     * listed — never the unfiltered index by accident.
+     *
+     * @param subject - The reader's own context, forwarded (viaToken / viaShare ride on it)
+     * @param action  - Legacy verb (`view`, `edit`) or policy action; default `view`
+     */
+    listPagesFor(subject: PermissionSubject | null | undefined, action?: string): Promise<string[]>;
+    /**
+     * Get all page titles (explicit alias for getAllPages)
+     * Prefer this for new code that only needs page names.
+     * Use getAllPageInfo() when you need uuid/slug/author etc.
+     */
+    /**
+     * #1006: how many pages this instance holds.
+     *
+     * Names, not pages: `getAllPageNames()` reads the index, where
+     * `getAllPages()` would load every page's content to count them.
+     */
+    getManagerStats(): Promise<ManagerStats>;
+    getAllPageNames(): Promise<string[]>;
+    /**
+     * Get a page by its UUID
+     * @param {string} uuid - Page UUID
+     * @returns {Promise<WikiPage | null>} Page or null if not found
+     */
+    getPageByUUID(uuid: string, ctx: ActorContext): Promise<WikiPage | null>;
+    /**
+     * Get a page by its slug
+     * @param {string} slug - URL-friendly slug
+     * @returns {Promise<WikiPage | null>} Page or null if not found
+     */
+    getPageBySlug(slug: string, ctx: ActorContext): Promise<WikiPage | null>;
+    /**
+     * Refresh internal cache/index
+     *
+     * Forces the provider to rebuild its internal caches and indices.
+     * Useful after external file system changes.
+     *
+     * @async
+     * @returns {Promise<void>}
+     *
+     * @example
+     * await pageManager.refreshPageList();
+     * console.log('Page list refreshed');
+     */
+    /**
+     * Return pages most recently modified, sorted descending by lastModified (#635).
+     *
+     * Delegates to the provider's in-memory state (pageIndex / pageCache) — no
+     * direct disk I/O. Honors private-page visibility based on `options.principals`;
+     * the provider derives the admin bypass from an `admin` principal (#1116).
+     *
+     * Used by RecentChangesPlugin and any other consumer that needs a "recent edits"
+     * feed. New code should prefer this over enumerating getAllPages().
+     */
+    getRecentChanges(ctx: ActorContext, options?: RecentChangesOptions): Promise<RecentChangeEntry[]>;
+    /**
+     * Every indexed page carrying an `addon` provenance stamp.
+     * Used by addon orphan detection; reads the in-memory index, no disk I/O.
+     * Returns [] on providers that do not maintain a page index.
+     */
+    getAddonSeededIndexEntries(): Array<{
+        uuid: string;
+        addon: string;
+        slug?: string;
+        title: string;
+    }>;
+    /**
+     * Set the `addon` stamp on an existing index entry without rewriting the page.
+     * Used by the boot-time back-fill. Returns false when unsupported or unchanged.
+     */
+    setIndexAddon(uuid: string, addonName: string): Promise<boolean>;
+    /**
+     * Pages owned by a given user (#640).
+     *
+     * Authorization: callers MUST verify the requesting user is allowed to ask
+     * about `username` (typically only their own username, or admin asking about
+     * another). The provider does not enforce this — it filters by `author` /
+     * `creator` only.
+     */
+    getPagesByCreator(username: string, ctx: ActorContext, options?: GetPagesByCreatorOptions): Promise<RecentChangeEntry[]>;
+    /**
+     * 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).
+     */
+    getPagesSharedWith(principals: string[], options?: PagesScanOptions): 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 —
+     * view, edit, lists, the attachment door — reaches the same rule.
+     *
+     * `pages/vaults/{user}/` and every store below it is owned by that user.
+     * Nobody else acts in it unless the owner delegated (a share the owner
+     * issued, once the store's Share switch exists — #1388). No role reaches in,
+     * admin included (security-posture P2: no `hasRole` as an allow).
+     *
+     * The owner is the one in the page's name (#1456), not frontmatter
+     * `author`, so reassigning `author` cannot move ownership (#711).
+     *
+     * Returns:
+     *   - `null`  — a public name; the caller falls through to its next tier
+     *   - `true`  — a private name, and the caller is the owner or the owner's delegate
+     *   - `false` — a private name, and the caller is neither — whether or not
+     *               the page exists
+     */
+    checkPrivatePageAccess(wikiContext: WikiContext, pageNameOrUuid: string): Promise<boolean | null>;
+    /**
+     * Owner and store of a private page, or `null` when the page is not private
+     * or does not exist (#1398). The owner owns the page and every attachment
+     * uploaded onto it, so AttachmentManager uses this to route a new upload into
+     * that owner's store.
+     *
+     * #1456: both come from the page's name, `private/{owner}/{store}/{title}`;
+     * the page is looked up in that store through `ctx` only to confirm it exists.
+     */
+    getPrivatePageOwner(pageNameOrUuid: string, ctx: ActorContext): Promise<{
+        creator: string;
+        store: string;
+    } | null>;
+    refreshPageList(): Promise<void>;
+    /**
+     * #1374: rewrite the provider's persistent page index from its last disk scan
+     * (run {@link refreshPageList} first). Null when the provider keeps no such
+     * index.
+     */
+    rebuildPageIndex(): Promise<{
+        pages: number;
+        changed: number;
+        removed: string[];
+        keptUnscanned: number;
+        historyInRequiredPages: number;
+    } | null>;
+    /**
+     * At unlock (#1456): the owner's sealed pages move from their user-level
+     * catalog into each encrypted store's own page index. Idempotent.
+     *
+     * @param ctx - The owner's context, holding the unlocked store keys
+     */
+    adoptUserPageCatalog(ctx: ActorContext): Promise<number>;
+    /**
+     * Run the link migrations at boot: over the unencrypted stores (#1457,
+     * #1506), then, once per site, `private/…` → `vaults/…` in the public pages
+     * (#1506).
+     *
+     * Best-effort: a failure is logged and never blocks start-up. An encrypted
+     * store is not readable here and is not touched — it migrates at its
+     * owner's unlock, through {@link migratePrivateLinks}.
+     */
+    migratePrivateLinksAtBoot(): Promise<void>;
+    /**
+     * `private/…` → `vaults/…` in every public page, once per site (#1506). The
+     * site records it in `site-migrations.json` in the instance data folder,
+     * beside `seeded-shipped-pages.json`; a second run would write nothing
+     * anyway ({@link rewriteLegacyVaultUrls}).
+     *
+     * @returns How many pages were rewritten
+     */
+    migrateVaultUrlsInPublicPages(ctx: ActorContext): Promise<number>;
+    /** Every vault on disk, as `owner/store` — encrypted ones included, since only their folder names are read. */
+    private listVaults;
+    /**
+     * Rewrite `[Title]` to `[store/Title]` in the private pages that mean it.
+     *
+     * Only a target naming a page in the SAME store is rewritten — never a
+     * public title, never another store — and a target that already parses as a
+     * private link is left alone, so a second run writes nothing
+     * ({@link rewriteToPrivateLinks}).
+     *
+     * Each page goes through {@link savePage}, so it is versioned, reindexed and
+     * audited as `link-rewrite`. It keeps its `lastModified` (operator,
+     * 2026-09-23: a syntax rewrite must not move a page to the top of Recent
+     * Changes) and its `editor`: nobody edited it.
+     *
+     * A store that has been migrated records it beside its own indexes and is
+     * skipped from then on. One store's failure never stops the others.
+     *
+     * @param ctx - Whose reading and writing this is (#1179). Only the stores
+     *   this context can open are visited: the system principal reaches the
+     *   unencrypted ones, an owner's own unlocked session reaches theirs.
+     * @param owner - One user's stores, or every readable store when omitted
+     * @returns How many pages were rewritten
+     */
+    migratePrivateLinks(ctx: ActorContext, owner?: string): Promise<number>;
+    /**
+     * One page's body rewritten by `rewrite`, saved through the door. Returns 1
+     * when it changed, 0 when it did not or could not be read or saved.
+     */
+    private rewritePage;
+    /**
+     * Move a private page into another of its owner's vaults (#1505), under the
+     * same title. The page, its history and its index entries go with it; it
+     * keeps its `lastModified` and `editor`, since nobody edited it. The audit
+     * record is a rename, from the old path to the new.
+     *
+     * Access is not decided here, as for every save: the caller has already
+     * been let into the page. A page is never moved out of an encrypted vault
+     * into one that is not, since that would write it in the clear.
+     *
+     * @param pageName - The page's private name, `vaults/{owner}/{vault}/{title}`
+     * @param toVault - The vault to move it to
+     * @param ctx - Who is acting (#1179)
+     * @param changes - Frontmatter to change in the same write, e.g. its `system-category`
+     * @returns Where the page landed
+     */
+    movePageToVault(pageName: string, toVault: string, ctx: ActorContext, changes?: Partial<PageFrontmatter>): Promise<PageSaveResult>;
+    /**
+     * Move the captures made before #1505 into the capture vault, with
+     * `system-category: capture`. Until then a capture was a `general` page
+     * carrying the system keyword `capture`, saved in its author's default
+     * vault. A page whose system-category someone changed is left where it is.
+     *
+     * Runs over the vaults `ctx` can open — at boot, the unencrypted ones — and
+     * each vault records that it is done. A page whose title is already taken
+     * in the capture vault stays where it is, and is still found there: the
+     * capture page looks in the capture vault, then the default one.
+     *
+     * @returns How many pages moved
+     */
+    moveCapturesToCaptureVault(ctx: ActorContext): Promise<number>;
+    /**
+     * Move private pages made before #1505 into their system-category's own
+     * vault (#1507). Until then every private page went to its owner's default
+     * vault, whatever its system-category — journal entries included. A page in
+     * the default vault whose system-category declares another vault
+     * (`storageLocation.privatestore`) moves there; a page in any other vault
+     * was put there on purpose and is left alone.
+     *
+     * Same rules as {@link moveCapturesToCaptureVault}: the vaults `ctx` can
+     * open, once per vault, and a page whose title is taken where it would go
+     * stays where it is.
+     *
+     * @returns How many pages moved
+     */
+    movePagesToCategoryVaults(ctx: ActorContext): Promise<number>;
+    /**
+     * Every private slug in the `vaults--…` form (#1507), once per vault. A
+     * private page's slug is made fresh on every save, so each page whose slug
+     * is anything else is saved again, unchanged otherwise: same body,
+     * `lastModified` and `editor`. That is `private--…` from before #1507, and a
+     * plain slug from before #1456, which could clash with a public page's.
+     *
+     * @returns How many pages were re-saved
+     */
+    migratePrivateSlugs(ctx: ActorContext): Promise<number>;
+    /**
+     * One pass of a vault move: every page in the vaults `ctx` can open is
+     * offered to `pick`, which names the vault it goes to (and any frontmatter
+     * to change with it), or null to leave it.
+     */
+    private moveVaultPages;
+    /**
+     * Visit every page in the vaults `ctx` can open — at boot, the unencrypted
+     * ones — once per vault: each vault records `migrationId` when visited, so
+     * no later boot reads its pages again. `visit` returns the vault the page
+     * was written to, or null when it left the page alone; one page's or one
+     * vault's failure never stops the rest.
+     *
+     * @returns How many pages were written
+     */
+    private visitVaultPages;
+    /**
+     * Every vault page the startup checks found with data outside its vault —
+     * files in the shared pool (#1842), footnotes or comments in the public
+     * folders (#1839) — as one list for the repair actions, with whether `ctx`
+     * may repair each one here and, if not, why. Read from the checks' last
+     * findings, so listing opens no vault. Only what `ctx` may see: every item
+     * for someone holding `admin-system` (owner, vault and page uuid, as the
+     * subsystem banner already shows), otherwise the items of their own vaults.
+     */
+    listVaultRepairs(ctx: ActorContext, opts?: {
+        details?: boolean;
+    }): Promise<VaultRepairItem[]>;
+    /**
+     * The pages of one repair item that `ctx` may read, as the reader sees
+     * them (#1842): each one read as `ctx` through {@link readPage}, the same
+     * door as viewing it, after the unrecorded {@link mayShowPage}, so a refusal
+     * never records a page name. Found through the vault stores `ctx` can open,
+     * so a sealed vault contributes nothing without its owner's key. Its
+     * outside files come from `AttachmentManager.poolFilesOfVaultPage`.
+     * Best-effort: a failure shows no details, and is logged without a title.
+     */
+    private vaultRepairPages;
+    /**
+     * Move one vault page's leftovers into its vault (#1842): the shared-pool
+     * files it uses (`AttachmentManager.movePoolFilesIntoVault`) and its
+     * footnotes and comments from the public folders
+     * (`FootnoteManager` / `CommentManager.moveOutside…IntoVault`), each by its
+     * own manager through the vault's store I/O — sealed when the vault is. A
+     * pool file another public page uses is copied, never taken from it.
+     *
+     * `page` null is the startup check's "pages named by shared records": every
+     * page of that vault a shared-pool record still names, files only.
+     *
+     * Who may: the vault's owner, in their own session (a sealed vault needs its
+     * key, so it must be open); for a vault that isn't sealed, also someone
+     * holding `admin-system`. A sealed vault asked for by anyone but its owner
+     * is refused, and nothing changes.
+     *
+     * Recorded as `vault-repair` before anything moves (on-failure refuse), with
+     * the counts it is about to move. Then the three checks run again, so the
+     * subsystem banner clears once nothing is left.
+     */
+    repairVaultPage(target: {
+        owner: string;
+        vault: string;
+        page: string | null;
+    }, ctx: ActorContext, opts?: {
+        recheck?: boolean;
+    }): Promise<VaultRepairResult>;
+    /**
+     * "Repair all I can" (#1842): every listed item `ctx` may repair, one by
+     * one through {@link repairVaultPage}; one item's failure never stops the
+     * rest. The checks run again once, at the end.
+     *
+     * @param opts.ownOnly - Only `ctx`'s own vaults (the profile's "Move all into my vaults")
+     */
+    repairAllVaultPages(ctx: ActorContext, opts?: {
+        ownOnly?: boolean;
+    }): Promise<{
+        repaired: number;
+        refused: number;
+        failed: number;
+    } & VaultRepairCounts>;
+    /** The three startup checks, run again (#1842). */
+    private recheckVaultRepairs;
+    private repairManagers;
+    private vaultPaths;
+    /** `admin-system`, asked of the PDP: `permits` at the door, `holds` for an affordance (#1635). */
+    private adminSystem;
+    /**
+     * Who may move leftovers into `owner`'s vault `vault` (#1842). The owner (the
+     * container rule, then `page-edit` in the vault, which `vault-owner` gives),
+     * with the vault open when it is sealed; for a vault that isn't sealed, also
+     * someone holding `admin-system` — the boot migration's reach (#1460),
+     * which writes into unsealed vaults with no owner present. A sealed vault
+     * needs its owner's key, so no one else can.
+     */
+    private repairAuthority;
+    /**
+     * Flush any pending write queues in the provider (e.g. page-index writes).
+     * Call before process exit to prevent data loss on unclean shutdown.
+     */
+    flushWriteQueue(): Promise<void>;
+    /**
+     * Shutdown the PageManager and its provider
+     *
+     * Cleanly shuts down the provider, closing connections and flushing caches.
+     *
+     * @async
+     * @returns {Promise<void>}
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Backup all pages through the provider
+     *
+     * Delegates to the provider's backup() method to serialize all page data.
+     * The backup includes all page content, metadata, and directory structure.
+     *
+     * @returns {Promise<BackupData>} Backup data from provider
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * Restore pages from backup data
+     *
+     * Delegates to the provider's restore() method to recreate all pages
+     * from the backup data.
+     *
+     * @param {BackupData} backupData - Backup data from backup() method
+     * @returns {Promise<void>}
+     */
+    restore(backupData: BackupData): Promise<void>;
+}
+export default PageManager;