@murumets-ee/content 0.0.0-preview-20261014110621

package/dist/resolve.d.mts

@@ -0,0 +1,651 @@
+import { Entity } from "@murumets-ee/entity";
+import { Logger, ToolkitApp } from "@murumets-ee/core";
+import { z } from "zod";
+//#region src/redirects/target.d.ts
+/** The stored shape of `toolkit_redirects.target`. */
+type RedirectTarget = {
+  kind: 'entity';
+  entity: string;
+  id: string;
+} | {
+  kind: 'url';
+  url: string;
+} | {
+  kind: 'path';
+  path: string;
+};
+//#endregion
+//#region src/paths/index-reader.d.ts
+/**
+ * Narrow read surface over `toolkit_paths` (plan/routing PR06).
+ *
+ * The resolution API (`./resolve.ts`) and the historical-tier helper
+ * (`./redirect-target.ts`) both read the path index, but neither needs the full
+ * `ToolkitPathsClient` — only `findOne` + `findMany`. Injecting a narrow
+ * structural interface (the same pattern `../redirects/validation.ts` uses for
+ * its readers) lets unit tests pass a trivial cast-free stub while the real
+ * `ToolkitPathsClient` still satisfies it (proven at compile time by the
+ * integration tests, which pass the real client straight in).
+ *
+ * The interface is deliberately a STRUCTURAL SUPERTYPE the real client is
+ * assignable to: every `where` field is a plain value (⊆ the client's richer
+ * `ColumnOperators` where-clause), `orderBy` only names `updatedAt` (a real
+ * column), and the projected {@link PathIndexRow} is a subset of the full row —
+ * so the assignment holds under TypeScript's method-parameter bivariance with no
+ * `as` casts on either side.
+ */
+/**
+ * The `toolkit_paths` fields the resolution + historical tiers actually read.
+ *
+ * Declared as a `type` (not `interface`) deliberately: the real
+ * `ToolkitPathsClient`'s `findOne`/`findMany` are typed against `WhereClause`,
+ * whose template-literal index signature (`[k: \`${string}.${string}\`]`) a
+ * named `interface` can't satisfy as a supertype — a `type`-alias object literal
+ * gets the implicit index signature and stays assignable. (Same reason
+ * `../redirects/validation.ts` uses inline anonymous reader params.)
+ */
+type PathIndexRow = {
+  entityType: string;
+  entityId: string;
+  locale: string;
+  path: string;
+  isCanonical: boolean;
+};
+/** The (plain-value) where shapes those tiers query by. `type`, per {@link PathIndexRow}. */
+type PathIndexWhere = {
+  entityType?: string;
+  entityId?: string;
+  locale?: string;
+  path?: string;
+  isCanonical?: boolean;
+};
+/** The read surface `getCanonicalPath` / `resolvePath` / `findRedirectTarget` need. */
+type PathIndexReader = {
+  findOne(where: PathIndexWhere): Promise<PathIndexRow | null>;
+  findMany(options: {
+    where?: PathIndexWhere; /** Only `updatedAt` ordering is used (historical-collision tie-break). */
+    orderBy?: Array<{
+      column: 'updatedAt';
+      dir?: 'asc' | 'desc';
+    }>;
+    limit?: number;
+  }): Promise<PathIndexRow[]>;
+};
+//#endregion
+//#region src/paths/homepage.d.ts
+/** A resolved pointer at the document that serves `/`. */
+interface HomepagePointer {
+  entity: string;
+  id: string;
+}
+/**
+ * Shape of the `homeDocument` JSONB value. `id` is a UUID — entity row ids
+ * are UUIDs across this codebase (only USER ids are varchar; CLAUDE.md).
+ */
+declare const homepagePointerSchema: z.ZodObject<{
+  entity: z.ZodString;
+  id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  id: string;
+  entity: string;
+}, {
+  id: string;
+  entity: string;
+}>;
+/**
+ * Parse a raw `homeDocument` value into a {@link HomepagePointer}, or `null`
+ * when it's unset / malformed. Never throws.
+ */
+declare function parseHomepagePointer(value: unknown): HomepagePointer | null;
+//#endregion
+//#region src/paths/resolve.d.ts
+/** The document that serves the requested path. */
+interface ResolveDocumentResult {
+  kind: 'document';
+  entityType: string;
+  id: string;
+}
+/** A redirect to another URL/path. `301` permanent, `302` temporary. */
+interface ResolveRedirectResult {
+  kind: 'redirect';
+  to: string;
+  status: 301 | 302;
+}
+/** Nothing routes here (404). */
+interface ResolveNoneResult {
+  kind: 'none';
+}
+type ResolveResult = ResolveDocumentResult | ResolveRedirectResult | ResolveNoneResult;
+/**
+ * Is `(entityType, entityId)` published in `locale`? Backed by
+ * `QueryClient.findById`, which applies the publish filter for any principal
+ * WITHOUT `view_unpublished` (D017) — so the answer is only "published" if the
+ * injected client's context withholds that action, which the real one
+ * (`resolve-context.ts`'s reach context) does. See {@link createPublishChecker}.
+ * `resolveDraftPath` bypasses this entirely.
+ */
+interface PublishChecker {
+  isPublished(entityType: string, entityId: string, locale: string): Promise<boolean>;
+}
+/** Resolve an entity TYPE NAME to its `Entity`, or `undefined` when unregistered. */
+type EntityResolver = (entityType: string) => Entity | undefined;
+/** The `QueryClient.findById` surface the publish checker needs (publish filter is internal). */
+interface PublishQueryClient {
+  findById(id: string, options?: {
+    locale?: string | undefined;
+  }): Promise<unknown>;
+}
+/** Build a publish-filtering read client for an entity (real: `new QueryClient(...)`). */
+type QueryClientFactory = (entity: Entity) => PublishQueryClient;
+/** Read the current homepage pointer, or `null` when unset/malformed. */
+type HomepageReader = () => Promise<HomepagePointer | null>;
+/** The manual-redirect lookup surface (locale-specific + catch-all rows). */
+interface RedirectLookupReader {
+  findOne(where: {
+    fromPath: string; /** A concrete locale, or `null` for the catch-all (all-locales) row. */
+    locale: string | null;
+  }): Promise<{
+    target: RedirectTarget;
+    status: number;
+  } | null>;
+}
+/** Deps for {@link getCanonicalPath} — the minimal index read. */
+interface CanonicalPathDeps {
+  pathsClient: PathIndexReader;
+}
+/** Deps for {@link resolvePath} / {@link resolveDraftPath}. */
+interface ResolvePathDeps extends CanonicalPathDeps {
+  redirectsClient: RedirectLookupReader;
+  publishChecker: PublishChecker;
+  homepageReader: HomepageReader;
+  /**
+   * Is this entity type still routable (does it declare `frontend.path`)? A
+   * `toolkit_paths` row outlives its entity losing the path (F068), so every
+   * tier that serves a row's document asks first: a row of a non-routable
+   * entity is `none`, never a document or a redirect. `buildResolveDeps`
+   * always supplies it; omitted (unit-test builders only) means "every entity
+   * is routable".
+   */
+  isRoutable?: (entityType: string) => boolean;
+  /**
+   * Optional so the unit-test deps builders stay unchanged. Its only use is
+   * letting the historical-redirect lookup report a truncated candidate window
+   * — see {@link findRedirectTarget}.
+   */
+  logger?: Logger;
+}
+/** Deps for {@link getAlternates}. */
+interface AlternatesDeps extends CanonicalPathDeps {
+  publishChecker: PublishChecker;
+  /** The locales to enumerate (configured content locales). */
+  locales: readonly string[];
+}
+/**
+ * Hop cap on manual-redirect `path`-chain following at REQUEST time (F021 /
+ * F027 point 4). `collapsePathTarget` only collapses ONE hop at save time, so a
+ * chain created out-of-order can still need re-hopping here; exceeding the cap
+ * resolves to `none` rather than looping or 500ing.
+ */
+declare const MAX_REDIRECT_HOPS = 5;
+/**
+ * The current canonical path for `(entityType, entityId, locale)`, or `null`
+ * when the document has no canonical row in that locale.
+ *
+ * **No publish filter — deliberate.** This matches the CURRENT behavior of
+ * `resolveEntityHref` / search's URL builder (both call `AdminClient.findById`,
+ * which does zero publish filtering); Task 2 re-points those consumers onto this
+ * function, so changing the filtering here would be an unplanned behavior change.
+ * Callers that need a publish gate compose one explicitly (resolution's canonical
+ * tier does).
+ */
+declare function getCanonicalPath(entityType: string, entityId: string, locale: string, deps: CanonicalPathDeps): Promise<string | null>;
+/**
+ * Build a {@link PublishChecker} from an entity resolver + a query-client
+ * factory. `isPublished` is `false` for an unknown entity type, else
+ * `findById(id, { locale }) !== null` — a non-null result means "published in
+ * that locale" because `QueryClient` applies the publish filter (and excludes
+ * trashed rows) for every principal without `view_unpublished` (D017). The
+ * factory therefore has to hand back a client whose context withholds that
+ * action; `resolve-context.ts`'s reach context is the one in-repo
+ * implementation and does. F027 point 1.
+ */
+declare function createPublishChecker(deps: {
+  entityResolver: EntityResolver;
+  queryClientFactory: QueryClientFactory;
+}): PublishChecker;
+/**
+ * Resolve `(path, locale)` to a document / redirect / none, publish-checking at
+ * every document-resolving tier. Public request surface (phase 05 §2).
+ */
+declare function resolvePath(path: string, locale: string, deps: ResolvePathDeps): Promise<ResolveResult>;
+/**
+ * Admin/preview resolution — identical tier structure to {@link resolvePath} but
+ * SKIPS every publish check (draft and published documents both resolve). Per
+ * phase 05 §2 this surface is admin-only. Exactly ONE HTTP route may call it —
+ * `./routes.ts`'s `GET /api/admin/paths/resolve` (#775), which gates on
+ * `path:resolve` and re-checks the caller's `view` grant on whatever it
+ * resolves. NEVER wire it to `content-api` (public, published-only).
+ */
+declare function resolveDraftPath(path: string, locale: string, deps: ResolvePathDeps): Promise<ResolveResult>;
+/**
+ * The published per-locale canonical URLs for a document — the `hreflang`
+ * alternates set (phase 05 §2, "published locales only"). A locale is included
+ * only when the document has a canonical row AND is published there. Bounded by
+ * the (small, fixed) configured-locale count — no fan-out concern.
+ */
+declare function getAlternates(entityType: string, id: string, deps: AlternatesDeps): Promise<Array<{
+  locale: string;
+  path: string;
+}>>;
+//#endregion
+//#region src/paths/enumerate.d.ts
+/**
+ * Path enumeration for SSG / sitemaps (plan/routing PR06; phase
+ * `05-resolution-and-enumeration-api.md` §2).
+ *
+ * `enumeratePaths` streams the PUBLISHED canonical `(path, entityType, id,
+ * updatedAt)` rows for one locale. It powers `getStaticPaths` + the sitemap
+ * helper, so it must NEVER leak an unpublished document (CLAUDE.md #1 — the
+ * output feeds public build artifacts).
+ *
+ * **Security + availability.** Two properties matter here:
+ *  1. *No unpublished leak.* `toolkit_paths` carries no publish-status column,
+ *     so each page's rows are publish-checked against the live entity via the
+ *     injected {@link EnumeratePathsDeps.filterPublished} — an unpublished (or
+ *     trashed) document is dropped from the stream.
+ *  2. *No unbounded fan-out* (CLAUDE.md "no amplification"). Work is bounded by
+ *     PAGE SIZE, not by total document count: rows are keyset-paginated on the
+ *     immutable `id` PK (one index query per page), and the publish check is
+ *     BATCHED — ONE call per distinct entity-type bucket per page (a handful of
+ *     types at most; the routable set is config-time-fixed, never
+ *     attacker-influenced), never one call per row.
+ *
+ * **Leaf module.** Every cross-package dependency (the index reader, the publish
+ * filter) is injected via `deps`; this module imports no `@murumets-ee/core` and
+ * no `server-only` graph. Concrete deps are built from an app in
+ * `./resolve-context.ts` (`buildEnumerateDeps`), keeping the resolution surface
+ * off the `lumi` CLI command graph (F027 guardrail).
+ *
+ * Function-form-path entities need NO special handling — their rows were already
+ * materialized into `toolkit_paths` at write time (F004 / phase 05 §2), so a
+ * plain index read includes them.
+ */
+/** The projected `toolkit_paths` row the enumeration + batch lookup read. */
+type PathEnumRow = {
+  id: string;
+  entityType: string;
+  entityId: string;
+  locale: string;
+  path: string;
+  updatedAt: Date;
+};
+/**
+ * The (operator-carrying) where shapes enumeration issues: keyset `id > cursor`,
+ * `entityId IN (...)` for the batch lookup, plus plain-value equality filters.
+ * A subset of the real client's `ColumnOperators` where-clause, so the real
+ * `ToolkitPathsClient` is assignable to {@link PathEnumReader}.
+ */
+type PathEnumWhere = {
+  id?: {
+    gt: string;
+  };
+  entityType?: string;
+  entityId?: {
+    in: string[];
+  };
+  locale?: string; /** `{ in }` for a batched membership read (`resolvePublishedPathsAmong`). */
+  path?: string | {
+    in: string[];
+  };
+  isCanonical?: boolean;
+};
+/**
+ * The batched keyset read surface {@link enumeratePaths} / {@link getCanonicalPaths}
+ * need. NARROWER than Task 1's point-lookup `PathIndexReader` (which only orders
+ * by `updatedAt` and takes plain-value where): enumeration needs `id`-ordering,
+ * a `{ gt }` cursor, and `{ in }` batching. Construct the real client directly
+ * (`toolkitPathsTable.makeClient(db)`) — it satisfies this type.
+ */
+type PathEnumReader = {
+  findMany(options: {
+    where?: PathEnumWhere;
+    orderBy?: Array<{
+      column: 'id';
+      dir?: 'asc' | 'desc';
+    }>;
+    limit?: number;
+  }): Promise<PathEnumRow[]>;
+};
+/**
+ * Batch publish check: return the SUBSET of `entityIds` that is published in
+ * `locale`. Called ONCE per entity-type group per page. The concrete
+ * implementation (see `resolve-context.ts`) runs an elevated-context
+ * `QueryClient.findMany({ where: inArray(getTable().id, ids), locale })` — so no
+ * unpublished/trashed id comes back. Since D017 the publish filter is
+ * CONDITIONAL (it holds for any principal without `view_unpublished`); what
+ * keeps that true here is that the elevated context is a REACH context which
+ * withholds that action, not that the filter is unconditional.
+ */
+type PublishFilter = (entityType: string, entityIds: readonly string[], locale: string) => Promise<ReadonlySet<string>>;
+/** One enumerated path row (phase 05 §2 — exact shape). */
+interface PathEntry {
+  path: string;
+  entityType: string;
+  id: string;
+  updatedAt: Date;
+}
+/** Options for {@link enumeratePaths} (phase 05 §2 — exact shape). */
+interface EnumeratePathsOptions {
+  /** Enumerate this locale's canonical rows only. */
+  locale: string;
+  /** Optionally narrow to a single routable entity type. */
+  entityType?: string;
+  /**
+   * Resume the keyset AFTER this `toolkit_paths` row id (exclusive); omit to
+   * start from the beginning. The value is the opaque `toolkit_paths` PK the
+   * internal page cursor advances on — NOT the yielded `PathEntry.id`, which is
+   * the DOCUMENT (entity) id. A cross-request paginating caller (e.g. the
+   * content-api `_paths` endpoint) resolves the last consumed entry's row PK and
+   * passes it here to continue exactly where the prior page stopped, with no row
+   * skipped or repeated. Fully backward-compatible: existing callers omit it and
+   * traverse from the start unchanged.
+   */
+  afterId?: string;
+}
+/** Injected dependencies for {@link enumeratePaths}. */
+interface EnumeratePathsDeps {
+  pathsClient: PathEnumReader;
+  filterPublished: PublishFilter;
+}
+/** Internal tuning seam (page size / batch concurrency). Real callers omit it. */
+interface EnumeratePathsTuning {
+  /** Rows per index page. Defaults to {@link ENUMERATE_PAGE_SIZE}. Tests force a small value. */
+  pageSize?: number;
+  /** Peak concurrent publish-check groups. Defaults to {@link PUBLISH_CHECK_CONCURRENCY}. */
+  publishConcurrency?: number;
+}
+/**
+ * Stream the published canonical paths for `opts.locale` (optionally narrowed to
+ * `opts.entityType`), keyset-paginated with a per-page batched publish filter.
+ * See the module header for the security + fan-out guarantees.
+ */
+declare function enumeratePaths(opts: EnumeratePathsOptions, deps: EnumeratePathsDeps, tuning?: EnumeratePathsTuning): AsyncGenerator<PathEntry>;
+/** Deps for {@link getCanonicalPaths}. */
+interface CanonicalPathsBatchDeps {
+  pathsClient: PathEnumReader;
+}
+/**
+ * The current canonical paths for many `(entityType, entityId)` in ONE locale,
+ * as an `entityId → path` map — the batched sibling of `getCanonicalPath`.
+ *
+ * **No publish filter — deliberate**, matching `getCanonicalPath` (and the
+ * search url builder it re-points): a search result's url is display-only and
+ * the caller already gates row visibility. One index query per {@link
+ * CANONICAL_BATCH_SIZE}-sized chunk (one query total for a normal search page),
+ * so it never fans out per row.
+ */
+declare function getCanonicalPaths(entityType: string, entityIds: readonly string[], locale: string, deps: CanonicalPathsBatchDeps): Promise<Map<string, string>>;
+//#endregion
+//#region src/paths/sitemap.d.ts
+/** Options for {@link generateSitemap}. */
+interface SitemapOptions {
+  /** The locales to emit a `<urlset>` for (configured content locales). */
+  locales: readonly string[];
+  /**
+   * The default locale — its URL is the `x-default` hreflang target. Explicit
+   * (NOT inferred from `locales` order) so callers stay unambiguous.
+   */
+  defaultLocale: string;
+  /** Absolute site origin, e.g. `https://example.com` (trailing slash tolerated). */
+  baseUrl: string;
+  /**
+   * Per-locale URL prefix rule (e.g. `(l) => l === 'en' ? '' : '/' + l`). The
+   * frontend owns the locale-prefix convention (D002); omitted → no prefix.
+   */
+  prefix?: (locale: string) => string;
+  /**
+   * Max `<url>` entries per file before splitting (sitemap protocol caps at
+   * 50 000). Defaults to {@link DEFAULT_MAX_URLS_PER_FILE}.
+   */
+  maxUrlsPerFile?: number;
+}
+/** Injected dependencies for {@link generateSitemap}. */
+interface SitemapDeps {
+  /**
+   * Deps for {@link enumeratePaths} — the `toolkit_paths` reader plus the
+   * batched `filterPublished`. `filterPublished` is REUSED for the cross-locale
+   * alternate publish gate (same batched shape), so no second publish surface is
+   * needed.
+   */
+  enumerate: EnumeratePathsDeps;
+  /**
+   * Deps for {@link getCanonicalPaths} — the batched cross-locale forward index
+   * read (NO publish filter; this module applies `enumerate.filterPublished` on
+   * top).
+   */
+  canonicalBatch: CanonicalPathsBatchDeps;
+  /**
+   * Optional: batched `noIndex` check, same shape as `filterPublished` but
+   * semantics-inverted — returns the subset of `entityIds` that ARE `noIndex`
+   * in `locale` (PR 11's `seoMeta()`). Called at most once per (entity-type
+   * group, batch), never once per entry — see `excludeNoIndexed`. Omitted →
+   * nothing excluded (current default).
+   */
+  filterNoIndex?: PublishFilter;
+}
+/** Internal tuning seam (batch size / enumerate page size). Real callers omit it. */
+interface SitemapTuning {
+  /**
+   * Enumerated rows per cross-locale alternate batch. Defaults to
+   * {@link SITEMAP_ALTERNATES_BATCH_SIZE}. Tests force a small value to span
+   * multiple batches. Bounds the per-batch fan-out (see module header).
+   */
+  batchSize?: number;
+  /** Passed through to {@link enumeratePaths} for its own paging/publish tuning. */
+  enumerate?: EnumeratePathsTuning;
+}
+/** One emitted sitemap document. */
+interface SitemapFile {
+  /** `'urlset'` for a per-locale URL set, `'index'` for the sitemap index. */
+  kind: 'urlset' | 'index';
+  /**
+   * Suggested filename served at `${baseUrl}/${filename}`. Per-locale urlsets are
+   * `sitemap-<locale>.xml` (first) / `sitemap-<locale>-<n>.xml` (splits, n≥2);
+   * the index is {@link SITEMAP_INDEX_FILENAME}.
+   */
+  filename: string;
+  /** The complete, well-formed XML document text (trailing newline included). */
+  xml: string;
+}
+/** Default `<url>` cap per file — under the sitemap protocol's 50 000 hard limit. */
+declare const DEFAULT_MAX_URLS_PER_FILE = 40000;
+/** Filename of the emitted sitemap index (referenced by the mounting route). */
+declare const SITEMAP_INDEX_FILENAME = "sitemap.xml";
+/**
+ * Stream the sitemap document set for `opts.locales`. See the module header for
+ * the security + fan-out guarantees. Yields each `<urlset>` file as it fills,
+ * then a `<sitemapindex>` LAST iff more than one file was produced.
+ */
+declare function generateSitemap(opts: SitemapOptions, deps: SitemapDeps, tuning?: SitemapTuning): AsyncGenerator<SitemapFile>;
+//#endregion
+//#region src/paths/site-sitemap.d.ts
+/** Options for {@link generateSiteSitemap} — everything else comes from the site record. */
+interface SiteSitemapOptions {
+  /** Per-locale URL prefix rule — the frontend owns it (routing D002). Omitted → none. */
+  prefix?: (locale: string) => string;
+  /** Max `<url>` entries per file (see `generateSitemap`). */
+  maxUrlsPerFile?: number;
+}
+/**
+ * Stream `site`'s sitemap document set. Throws when the site does not exist or
+ * declares no public origin (a sitemap of relative URLs is not a sitemap).
+ */
+declare function generateSiteSitemap(app: ToolkitApp, site: string, options?: SiteSitemapOptions, tuning?: SitemapTuning): AsyncGenerator<SitemapFile>;
+//#endregion
+//#region src/paths/redirects-list.d.ts
+/** The projected `toolkit_redirects` row the manual-redirect enumeration reads. */
+type RedirectListRow = {
+  id: string;
+  fromPath: string; /** BCP47 locale, or `null` for the catch-all (all-locales) row. */
+  locale: string | null;
+  target: RedirectTarget;
+  status: number;
+};
+/**
+ * The (operator-carrying) where shapes the manual enumeration issues: a keyset
+ * `id > cursor` plus a `locale` equality (a concrete locale, or `null` for the
+ * catch-all stratum). A subset of the real client's `WhereClause`, so the real
+ * `ToolkitRedirectsClient` is assignable to {@link RedirectListReader}.
+ */
+type RedirectListWhere = {
+  id?: {
+    gt: string;
+  };
+  locale?: string | null;
+};
+/**
+ * The batched keyset read surface the manual half needs over `toolkit_redirects`.
+ * Construct the real client directly (`toolkitRedirectsTable.makeClient(db)`) —
+ * it satisfies this type.
+ */
+type RedirectListReader = {
+  findMany(options: {
+    where?: RedirectListWhere;
+    orderBy?: Array<{
+      column: 'id';
+      dir?: 'asc' | 'desc';
+    }>;
+    limit?: number;
+  }): Promise<RedirectListRow[]>;
+};
+/** One emitted redirect. `301` permanent, `302` temporary (phase 05 §2 shape). */
+interface RedirectEntry {
+  from: string;
+  to: string;
+  status: 301 | 302;
+}
+/** Options for {@link getRedirects}. */
+interface RedirectsListOptions {
+  /** Emit this locale's redirects only (mirrors `enumeratePaths` / `generateSitemap`). */
+  locale: string;
+}
+/** Injected dependencies for {@link getRedirects}. */
+interface RedirectsListDeps {
+  /** Keyset reader over `toolkit_redirects` (manual redirects). */
+  redirectsClient: RedirectListReader;
+  /**
+   * Keyset reader over `toolkit_paths` — the historical (non-canonical) rows AND
+   * the `path`-kind existence check. Reuses `enumeratePaths`'s exact reader shape.
+   */
+  pathsClient: PathEnumReader;
+  /** Batched forward index read for owning-document current-canonical resolution. */
+  canonicalBatch: CanonicalPathsBatchDeps;
+  /** The SAME batched publish filter `enumeratePaths` / `generateSitemap` use. */
+  filterPublished: PublishFilter;
+}
+/** Internal tuning seam (page size). Real callers omit it. */
+interface RedirectsListTuning {
+  /** Rows per keyset page. Defaults to {@link REDIRECTS_PAGE_SIZE}. Tests force a small value. */
+  pageSize?: number;
+}
+/**
+ * Stream the redirect list for `opts.locale`: manual redirects (locale-specific
+ * then catch-all, deduped by precedence) followed by historical redirects
+ * (skipping any `from` a manual redirect already claimed). See the module header
+ * for the security + fan-out + precedence guarantees.
+ */
+declare function getRedirects(opts: RedirectsListOptions, deps: RedirectsListDeps, tuning?: RedirectsListTuning): AsyncGenerator<RedirectEntry>;
+//#endregion
+//#region src/paths/site-scope.d.ts
+/** Resolves the site an access acts on — see the module docblock. */
+type SiteSource = () => Promise<string>;
+//#endregion
+//#region src/paths/resolve-context.d.ts
+/**
+ * Every builder below is SITE-CONFINED (plan `multisite` phase 03): its
+ * `toolkit_paths` / `toolkit_redirects` readers, its publish checks and its
+ * homepage reader all act on ONE site.
+ *
+ * - Omit `site` and that is the site of the request RUNNING the call (resolved
+ *   at call time, so a bundle built once per app still follows each request) —
+ *   its explicit `RequestContext.site`, else the single-site answer, else a
+ *   `SiteRequiredError`. This is every existing caller, unchanged.
+ * - Pass `site` to pin one explicitly (a per-site sitemap or warmer run from a
+ *   site-less job). Pinning inside a request confined to another site throws.
+ */
+interface SiteScopeOptions {
+  site?: string;
+}
+/**
+ * Build the minimal deps for {@link import('./resolve.js').getCanonicalPath} —
+ * just the `toolkit_paths` reader. Task 2's `resolveEntityHref` / search
+ * url-builder re-points use this (no publish checker / settings machinery).
+ */
+declare function buildCanonicalPathDeps(app: ToolkitApp, options?: SiteScopeOptions): CanonicalPathDeps;
+/**
+ * Build a live {@link PublishChecker} that reads through an elevated-context
+ * `QueryClient` per entity (publish filter auto-applied). See file header.
+ */
+declare function buildPublishChecker(app: ToolkitApp, options?: SiteScopeOptions): PublishChecker;
+/**
+ * Build the homepage reader for a site (plan `multisite` D007): the site
+ * registry row's `homeDocument` (`readSiteRecord` — read with reach, cached
+ * briefly), zod-parsed defensively (unset / malformed → `null`, never a throw
+ * — this runs on every `/` request).
+ *
+ * The pointer is only as good as the resolution that follows it: `/` publish-
+ * checks the document through a client confined to the SAME site, so a pointer
+ * at another site's document (legacy data, a hand-edited row) resolves to
+ * `none` instead of serving it (D006, defence in depth — writes are refused
+ * by `setSiteHomepage`).
+ */
+declare function createHomepageReader(app: ToolkitApp, siteOf: SiteSource): HomepageReader;
+/**
+ * Build the deps for {@link import('./enumerate.js').enumeratePaths} — the
+ * `toolkit_paths` reader plus a BATCHED publish filter. `filterPublished` runs
+ * ONE elevated-context `QueryClient.findMany({ where: inArray(getTable().id,
+ * ids), locale })` per entity-type group (not per row) — the trash filter
+ * applies unconditionally, and the publish filter applies because the elevated
+ * context WITHHOLDS `view_unpublished` (D017; see file header), so no
+ * unpublished/trashed id is returned. An unknown/unregistered entity type yields the empty set (its
+ * rows are treated as unpublished → dropped, fail-closed).
+ */
+declare function buildEnumerateDeps(app: ToolkitApp, options?: SiteScopeOptions): EnumeratePathsDeps;
+/**
+ * Build the deps for {@link import('./enumerate.js').getCanonicalPaths} — just
+ * the `toolkit_paths` reader (batched, NO publish filter, like
+ * {@link buildCanonicalPathDeps}). Task 2's search url re-point uses this to
+ * resolve a search page's result urls from the index in one query.
+ */
+declare function buildCanonicalPathsBatchDeps(app: ToolkitApp, options?: SiteScopeOptions): CanonicalPathsBatchDeps;
+/**
+ * Build the deps for {@link import('./sitemap.js').generateSitemap} — the
+ * one-stop bundle of {@link buildEnumerateDeps} (per-locale enumeration + its
+ * BATCHED publish filter, reused for the cross-locale alternate publish gate),
+ * {@link buildCanonicalPathsBatchDeps} (the batched cross-locale forward index
+ * read), and {@link buildNoIndexFilter} (PR 11's batched `noIndex` exclusion).
+ * Mirrors `buildResolveDeps`'s one-stop-deps pattern.
+ */
+declare function buildSitemapDeps(app: ToolkitApp, options?: SiteScopeOptions): SitemapDeps;
+/**
+ * Build the deps for {@link import('./redirects-list.js').getRedirects} — the
+ * one-stop bundle for the build-time redirect list (PR08). Composes
+ * {@link buildEnumerateDeps} (its `toolkit_paths` reader powers both the
+ * historical keyset and the `path`-kind existence check; its BATCHED
+ * `filterPublished` is the shared publish gate), {@link buildCanonicalPathsBatchDeps}
+ * (the batched owning-document current-canonical lookup), and a
+ * `toolkit_redirects` reader for the manual-redirect keyset. Mirrors
+ * {@link buildSitemapDeps}'s one-stop-deps style.
+ */
+declare function buildRedirectsListDeps(app: ToolkitApp, options?: SiteScopeOptions): RedirectsListDeps;
+/**
+ * Build the full {@link ResolvePathDeps} (+ {@link AlternatesDeps}) from an app —
+ * the one-stop deps for `resolvePath` / `resolveDraftPath` / `getAlternates`.
+ * `locales` are the statically-configured content locales (v1 — matches the
+ * redirect routes' own configured-locale source; DB-merged locale overrides are
+ * a later refinement).
+ */
+declare function buildResolveDeps(app: ToolkitApp, options?: SiteScopeOptions): ResolvePathDeps & AlternatesDeps;
+//#endregion
+export { type AlternatesDeps, type CanonicalPathDeps, type CanonicalPathsBatchDeps, DEFAULT_MAX_URLS_PER_FILE, type EntityResolver, type EnumeratePathsDeps, type EnumeratePathsOptions, type EnumeratePathsTuning, type HomepagePointer, type HomepageReader, MAX_REDIRECT_HOPS, type PathEntry, type PathEnumReader, type PathEnumRow, type PathEnumWhere, type PathIndexReader, type PathIndexRow, type PathIndexWhere, type PublishChecker, type PublishFilter, type PublishQueryClient, type QueryClientFactory, type RedirectEntry, type RedirectListReader, type RedirectListRow, type RedirectListWhere, type RedirectLookupReader, type RedirectsListDeps, type RedirectsListOptions, type RedirectsListTuning, type ResolveDocumentResult, type ResolveNoneResult, type ResolvePathDeps, type ResolveRedirectResult, type ResolveResult, SITEMAP_INDEX_FILENAME, type SiteScopeOptions, type SiteSitemapOptions, type SitemapDeps, type SitemapFile, type SitemapOptions, type SitemapTuning, buildCanonicalPathDeps, buildCanonicalPathsBatchDeps, buildEnumerateDeps, buildPublishChecker, buildRedirectsListDeps, buildResolveDeps, buildSitemapDeps, createHomepageReader, createPublishChecker, enumeratePaths, generateSiteSitemap, generateSitemap, getAlternates, getCanonicalPath, getCanonicalPaths, getRedirects, homepagePointerSchema, parseHomepagePointer, resolveDraftPath, resolvePath };
+//# sourceMappingURL=resolve.d.mts.map

package/dist/resolve.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.mts","names":[],"sources":["../src/redirects/target.ts","../src/paths/index-reader.ts","../src/paths/homepage.ts","../src/paths/resolve.ts","../src/paths/enumerate.ts","../src/paths/sitemap.ts","../src/paths/site-sitemap.ts","../src/paths/redirects-list.ts","../src/paths/site-scope.ts","../src/paths/resolve-context.ts"],"mappings":"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"}