@fern-api/fdr-sdk 1.2.165-67370398 → 1.2.165-757da63274

package/dist/docs-ledger/buildLedgerManifest.js

@@ -0,0 +1,885 @@
+import assertNever from "@fern-api/ui-core-utils/assertNever";
+import { collectConfigFilePaths, LEDGER_MANIFEST_SCHEMA_VERSION, LEDGER_SHARD_SCHEMA_VERSION, LedgerLocaleConfigOverrideSchema, LedgerSegmentDetailMetadataSchema, LedgerSegmentMetadataSchema, ledgerSegmentIdentity, selectLedgerSegmentsForLocale } from "../orpc-client/index.js";
+import { stableHash, stableStringify } from "./stableHash.js";
+import { toBasepathRelative } from "./toBasepathRelative.js";
+/**
+ * Soft byte target for a single route shard's serialized JSON (ADR 0016). Scopes
+ * are bin-packed (first-fit-decreasing) so each shard stays at or under this
+ * size; a single scope larger than the target becomes its own oversized shard,
+ * still well under the 1 MB per-object budget in practice.
+ */
+const LEDGER_SHARD_TARGET_BYTES = 700 * 1024;
+/**
+ * Maps a pruned-API artifact's metadata id field to the `nodeType` discriminator
+ * used by the read path. The manifest keys pruned blobs by `${nodeType}:${nodeId}`.
+ */
+const PRUNED_NODE_ID_FIELDS = [
+    ["endpointId", "endpoint"],
+    ["webSocketId", "webSocket"],
+    ["webhookId", "webhook"],
+    ["grpcId", "grpc"],
+    ["graphqlOperationId", "graphql"],
+    ["typeId", "graphqlType"]
+];
+function defaultContentTypeForArtifactType(type) {
+    switch (type) {
+        case "markdown":
+        case "changelog":
+            return "text/markdown";
+        case "rest":
+        case "asyncapi":
+        case "webhook":
+        case "grpc":
+        case "graphql":
+        case "graphqlType":
+            return "application/json";
+        default:
+            return "application/octet-stream";
+    }
+}
+function detailToManifest(detail) {
+    if (detail == null) {
+        return null;
+    }
+    return {
+        id: detail.hash,
+        displayName: detail.displayName,
+        icon: detail.icon ?? null,
+        sortOrder: detail.sortOrder,
+        hidden: detail.hidden,
+        viewers: detail.viewers,
+        orphaned: detail.orphaned,
+        featureFlags: detail.featureFlags,
+        metadata: LedgerSegmentDetailMetadataSchema.parse(detail.metadata)
+    };
+}
+function metadataField(metadata, key) {
+    return metadata != null && typeof metadata === "object" && key in metadata
+        ? metadata[key]
+        : undefined;
+}
+function addFileIconPath(paths, icon) {
+    if (typeof icon === "string" && icon.startsWith("file:")) {
+        const fullPath = icon.slice("file:".length);
+        if (fullPath !== "") {
+            paths.add(fullPath);
+        }
+    }
+}
+function addFilePath(paths, filePath) {
+    if (typeof filePath !== "string" || filePath === "") {
+        return;
+    }
+    const fullPath = filePath.startsWith("file:") ? filePath.slice("file:".length) : filePath;
+    if (fullPath !== "") {
+        paths.add(fullPath);
+    }
+}
+/**
+ * File paths referenced by navigation chrome must remain in the pointer-level
+ * `files` map because ProductSelectChrome/SidebarChrome resolve them via
+ * `loader.resolveFiles()` (`fileMetadata`/`fileArtifact`), not via page route
+ * shards. If the same asset is also embedded in page MDX, the page-file sharder
+ * would otherwise move it into a shard and prune it from the pointer, making the
+ * navigation icon/image disappear on the ledger path.
+ */
+function collectNavigationChromeFilePaths({ segmentDetails, segments, artifacts }) {
+    const paths = new Set();
+    for (const detail of segmentDetails) {
+        addFileIconPath(paths, detail.icon);
+        addFilePath(paths, metadataField(detail.metadata, "image"));
+    }
+    for (const segment of segments) {
+        addFileIconPath(paths, metadataField(segment.metadata, "icon"));
+    }
+    for (const artifact of artifacts) {
+        addFileIconPath(paths, metadataField(artifact.metadata, "icon"));
+    }
+    return [...paths];
+}
+function manifestRouteArtifactFields(artifact) {
+    switch (artifact.type) {
+        case "markdown":
+            return { artifactType: "markdown", artifactMetadata: artifact.metadata };
+        case "page":
+            return { artifactType: "page", artifactMetadata: artifact.metadata };
+        case "rest":
+            return { artifactType: "rest", artifactMetadata: artifact.metadata };
+        case "asyncapi":
+            return { artifactType: "asyncapi", artifactMetadata: artifact.metadata };
+        case "webhook":
+            return { artifactType: "webhook", artifactMetadata: artifact.metadata };
+        case "grpc":
+            return { artifactType: "grpc", artifactMetadata: artifact.metadata };
+        case "graphql":
+            return { artifactType: "graphql", artifactMetadata: artifact.metadata };
+        case "graphqlType":
+            return { artifactType: "graphqlType", artifactMetadata: artifact.metadata };
+        case "changelog":
+            return { artifactType: "changelog", artifactMetadata: artifact.metadata };
+        case "link":
+            return { artifactType: "link", artifactMetadata: artifact.metadata };
+        case "file":
+            return { artifactType: "file", artifactMetadata: artifact.metadata };
+        case "image":
+            return { artifactType: "image", artifactMetadata: artifact.metadata };
+        case "redirect":
+            return { artifactType: "redirect", artifactMetadata: artifact.metadata };
+        default:
+            return assertNever(artifact);
+    }
+}
+/**
+ * Overlay CAS content `created_at` onto the artifact-keyed `createdAt` map
+ * used for manifest route entries (sitemap `<lastmod>`). Artifact hashes are
+ * salted with `FDR_VERSION`, so their rows are re-minted on the first publish
+ * after every FDR deploy; the unsalted content row survives deploys and
+ * reflects when the page bytes first appeared. Content-less artifacts (links,
+ * files) keep the artifact row's timestamp.
+ */
+export function overlayContentCreatedAt({ artifacts, artifactHashToCreatedAt, contentHashToCreatedAt }) {
+    const merged = new Map(artifactHashToCreatedAt);
+    for (const artifact of artifacts) {
+        if (artifact.contentHash == null) {
+            continue;
+        }
+        const contentCreatedAt = contentHashToCreatedAt.get(artifact.contentHash);
+        if (contentCreatedAt != null) {
+            merged.set(artifact.hash, contentCreatedAt);
+        }
+    }
+    return merged;
+}
+/**
+ * Assemble the pointer + immutable CAS read model (ADR 0016) from the
+ * in-memory transform result the DAO just persisted. No DB read-back: every
+ * field comes from `params` / `baseResult` / `inlineTranslations`, and segment /
+ * artifact ids are content hashes (the S3-only reader never correlates against
+ * postgres).
+ *
+ * Leaf content (page markdown, API definitions) is referenced by CAS hash only
+ * — the bundle fetches those blobs directly. Hot-path chrome text
+ * (header/footer/css.inline/js.inline) is re-inlined into the pointer so page
+ * renders do not pay extra CAS reads for site chrome.
+ */
+export function buildLedgerReadModel(args) {
+    const { params, baseResult, inlineTranslations } = args;
+    // ── Merge base + translation locales ──────────────────────────────
+    const segmentDetails = [
+        ...params.segmentDetails,
+        ...inlineTranslations.flatMap((t) => t.segmentDetails)
+    ];
+    const artifacts = [...params.artifacts, ...inlineTranslations.flatMap((t) => t.artifacts)];
+    const segments = [...params.segments, ...inlineTranslations.flatMap((t) => t.segments)];
+    const nav = [...params.nav, ...inlineTranslations.flatMap((t) => t.nav)];
+    const deploymentSegments = [
+        ...params.deploymentSegments,
+        ...inlineTranslations.flatMap((t) => t.deploymentSegments)
+    ];
+    const detailByHash = new Map();
+    for (const d of segmentDetails) {
+        detailByHash.set(d.hash, d);
+    }
+    const artifactByHash = new Map();
+    for (const a of artifacts) {
+        artifactByHash.set(a.hash, a);
+    }
+    const segmentByHash = new Map();
+    for (const s of segments) {
+        segmentByHash.set(s.hash, s);
+    }
+    const sortOrderBySegment = new Map();
+    for (const ds of deploymentSegments) {
+        if (!sortOrderBySegment.has(ds.segmentHash)) {
+            sortOrderBySegment.set(ds.segmentHash, ds.sortOrder);
+        }
+    }
+    const contentTypeByHash = new Map();
+    for (const ref of baseResult.contentRefs.values()) {
+        contentTypeByHash.set(ref.hash, ref.contentType);
+    }
+    const contentType = (hash, artifactType) => contentTypeByHash.get(hash) ?? defaultContentTypeForArtifactType(artifactType);
+    // First nav entry per artifact (used to anchor pageId → fullPath/segment).
+    const firstNavByArtifact = new Map();
+    // Every locale an artifact is reachable from, via the segments navigating to it.
+    const localesByArtifact = new Map();
+    for (const n of nav) {
+        if (!firstNavByArtifact.has(n.artifactHash)) {
+            firstNavByArtifact.set(n.artifactHash, n);
+        }
+        const navLocale = segmentByHash.get(n.segmentHash)?.locale;
+        if (navLocale != null) {
+            const artifactLocales = localesByArtifact.get(n.artifactHash) ?? new Set();
+            artifactLocales.add(navLocale);
+            localesByArtifact.set(n.artifactHash, artifactLocales);
+        }
+    }
+    // ── segments ──────────────────────────────────────────────────────
+    const manifestSegments = segments.map((seg) => ({
+        segmentId: seg.hash,
+        segmentHash: seg.hash,
+        section: seg.section,
+        locale: seg.locale,
+        sortOrder: sortOrderBySegment.get(seg.hash) ?? 0,
+        hidden: seg.hidden,
+        metadata: LedgerSegmentMetadataSchema.parse(seg.metadata),
+        product: detailToManifest(seg.productHash != null ? detailByHash.get(seg.productHash) : undefined),
+        version: detailToManifest(seg.versionHash != null ? detailByHash.get(seg.versionHash) : undefined),
+        variant: detailToManifest(seg.variantHash != null ? detailByHash.get(seg.variantHash) : undefined),
+        tab: detailToManifest(seg.tabHash != null ? detailByHash.get(seg.tabHash) : undefined)
+    }));
+    // ── nav (sidebar trees) + routes (routable artifacts) ─────────────
+    // Cleaned deployment basepath (no leading/trailing slashes). Sidebar
+    // `fullPath`s are stored basepath-RELATIVE so the read-side nav builder
+    // re-prefixes them exactly once; see {@link toBasepathRelative}.
+    const basePrefix = args.basepath.replace(/^\/+|\/+$/g, "");
+    const navBySegment = {};
+    // locale → fullPath → route.
+    const routesByLocale = {};
+    const pagesByLocale = {};
+    // Sidebar order is per (segment) by displaySortOrder; build a sortable list first.
+    const sidebarEntries = nav
+        .filter((n) => n.displaySortOrder != null)
+        .sort((a, b) => (a.displaySortOrder ?? 0) - (b.displaySortOrder ?? 0));
+    for (const n of sidebarEntries) {
+        const artifact = artifactByHash.get(n.artifactHash);
+        if (artifact == null) {
+            continue;
+        }
+        const { hash: artifactId, contentHash: _contentHash, fileKey: _fileKey, ...artifactRouteFields } = artifact;
+        (navBySegment[n.segmentHash] ??= []).push({
+            ...artifactRouteFields,
+            // Basepath-relative: the read-side builder re-joins the basepath.
+            // Keeping it absolute here double-prefixes content node slugs on
+            // non-empty-basepath sites (→ every page resolves to notFound).
+            fullPath: n.fullPath != null ? toBasepathRelative(n.fullPath, basePrefix) : null,
+            artifactId,
+            // Preserve the absolute sidebar position so the read-side nav builder
+            // can interleave leaf pages (displaySortOrder) with subsections
+            // (childIndex) in the same coordinate space. Without this the reader
+            // falls back to compacted array indices and misorders mixed levels.
+            displaySortOrder: n.displaySortOrder
+        });
+    }
+    // Track fullPaths already claimed by a canonical (sidebar) nav entry so
+    // that cross-segment collisions (e.g. a section overview and its child
+    // apiReference overview sharing the same slug via skipUrlSlug) are resolved
+    // in favour of the first canonical entry — the parent section's artifact.
+    const canonicalRoutes = {};
+    for (const n of nav) {
+        if (n.fullPath == null) {
+            continue;
+        }
+        const artifact = artifactByHash.get(n.artifactHash);
+        const segment = segmentByHash.get(n.segmentHash);
+        if (artifact == null || segment == null) {
+            continue;
+        }
+        const routesForLocale = (routesByLocale[segment.locale] ??= {});
+        const canonicalForLocale = (canonicalRoutes[segment.locale] ??= new Set());
+        if (routesForLocale[n.fullPath] != null) {
+            // Route-only alias never overwrites an existing entry.
+            if (n.displaySortOrder == null) {
+                continue;
+            }
+            // First canonical entry wins — later canonical entries from sibling
+            // segments must not overwrite (prevents content resolution picking
+            // the wrong overview artifact when two segments share a fullPath).
+            if (canonicalForLocale.has(n.fullPath)) {
+                continue;
+            }
+        }
+        if (n.displaySortOrder != null) {
+            canonicalForLocale.add(n.fullPath);
+        }
+        const createdAt = args.artifactHashToCreatedAt?.get(n.artifactHash);
+        routesForLocale[n.fullPath] = {
+            segmentHash: n.segmentHash,
+            sidebarKey: n.segmentHash,
+            section: segment.section,
+            locale: segment.locale,
+            artifactId: n.artifactHash,
+            pageId: typeof artifact.metadata?.pageId === "string" ? artifact.metadata.pageId : undefined,
+            ...manifestRouteArtifactFields(artifact),
+            contentHash: artifact.contentHash,
+            contentType: artifact.contentHash != null ? contentType(artifact.contentHash, artifact.type) : null,
+            ...(createdAt != null ? { createdAt } : {})
+        };
+    }
+    // ── pages (pageId → content) ──────────────────────────────────────
+    for (const artifact of artifactByHash.values()) {
+        const pageId = artifact.metadata?.pageId;
+        if (typeof pageId !== "string" || artifact.contentHash == null) {
+            continue;
+        }
+        const anchorNav = firstNavByArtifact.get(artifact.hash);
+        const anchorSegment = anchorNav != null ? segmentByHash.get(anchorNav.segmentHash) : undefined;
+        const pageLocale = anchorSegment?.locale ?? params.deployment.defaultLocale ?? "en";
+        const pages = (pagesByLocale[pageLocale] ??= {});
+        pages[pageId] = {
+            fullPath: anchorNav?.fullPath ?? null,
+            segmentHash: anchorNav?.segmentHash ?? "",
+            contentHash: artifact.contentHash,
+            contentType: contentType(artifact.contentHash, artifact.type)
+        };
+    }
+    const defaultLocale = params.deployment.defaultLocale ?? params.segments[0]?.locale ?? "en";
+    // ── API definitions (full + pruned) ───────────────────────────────
+    // Full-definition hashes are locale-independent; pruned blobs are NOT. A
+    // translated locale's pruned artifacts carry the SAME apiDefinitionId and
+    // node ids as the base locale's, so they must be bucketed by the locale of
+    // the segment they are navigated from — a single shared map lets one
+    // locale's content overwrite every other locale's.
+    const apiDefs = {};
+    const apiNameToId = {};
+    for (const def of params.apiDefinitions) {
+        apiDefs[def.apiDefinitionId] = {
+            hash: def.contentHash,
+            contentType: "application/json",
+            prunedHashes: {}
+        };
+        if (def.apiName != null) {
+            apiNameToId[def.apiName] = def.apiDefinitionId;
+        }
+    }
+    // locale → apiDefinitionId → `${nodeType}:${nodeId}` → pruned CAS blob.
+    const prunedHashesByLocale = {};
+    for (const artifact of artifactByHash.values()) {
+        const apiDefinitionId = artifact.metadata?.apiDefinitionId;
+        if (typeof apiDefinitionId !== "string" || artifact.contentHash == null) {
+            continue;
+        }
+        const match = PRUNED_NODE_ID_FIELDS.map(([field, nodeType]) => {
+            const nodeId = artifact.metadata?.[field];
+            return typeof nodeId === "string" ? { nodeType, nodeId } : undefined;
+        }).find((m) => m != null);
+        if (match == null) {
+            continue;
+        }
+        const ref = {
+            hash: artifact.contentHash,
+            contentType: contentType(artifact.contentHash, artifact.type)
+        };
+        // An identical artifact can be navigated from several locales (an
+        // untranslated endpoint dedupes to one content hash), so register it
+        // under every locale that reaches it rather than just the first.
+        for (const artifactLocale of localesByArtifact.get(artifact.hash) ?? [defaultLocale]) {
+            const forLocale = (prunedHashesByLocale[artifactLocale] ??= {});
+            const forApi = (forLocale[apiDefinitionId] ??= {});
+            forApi[`${match.nodeType}:${match.nodeId}`] = ref;
+        }
+    }
+    // ── files (docs-bucket file/image artifacts) ──────────────────────
+    const bucketByFullPath = new Map();
+    for (const f of [...params.files, ...inlineTranslations.flatMap((t) => t.files)]) {
+        if (!bucketByFullPath.has(f.fullPath)) {
+            bucketByFullPath.set(f.fullPath, f.bucket);
+        }
+    }
+    const files = {};
+    const defaultBucket = args.isPrivate ? "private_docs" : "public_docs";
+    // File bytes are anchored on the canonical fern domain regardless of which
+    // URL this manifest is served at (ADR 0010), so files.domain is always the
+    // canonical site domain, not the per-URL pointer domain.
+    const fileDomain = args.fileDomain ?? params.site.domain;
+    for (const fe of baseResult.fileEntries) {
+        const isImage = fe.width != null && fe.height != null;
+        files[fe.fullPath] = {
+            type: isImage ? "image" : "file",
+            contentType: fe.contentType,
+            contentLength: fe.contentLength,
+            filename: fe.filename,
+            hash: fe.hash,
+            domain: fileDomain,
+            bucket: bucketByFullPath.get(fe.fullPath) ?? defaultBucket,
+            ...(fe.width != null ? { width: fe.width } : {}),
+            ...(fe.height != null ? { height: fe.height } : {}),
+            ...(fe.blurDataURL != null ? { blurDataURL: fe.blurDataURL } : {})
+        };
+    }
+    // Translation-only files carry no dimensions; record them as plain files.
+    for (const t of inlineTranslations) {
+        for (const f of t.files) {
+            if (files[f.fullPath] != null) {
+                continue;
+            }
+            files[f.fullPath] = {
+                type: "file",
+                contentType: f.contentType,
+                filename: f.fullPath.split("/").pop() ?? f.fullPath,
+                hash: f.hash,
+                domain: fileDomain,
+                bucket: f.bucket
+            };
+        }
+    }
+    const locales = new Set([defaultLocale]);
+    for (const seg of manifestSegments) {
+        locales.add(seg.locale);
+    }
+    for (const locale of Object.keys(routesByLocale)) {
+        locales.add(locale);
+    }
+    for (const locale of Object.keys(pagesByLocale)) {
+        locales.add(locale);
+    }
+    const segmentsForLocale = (locale) => selectLedgerSegmentsForLocale(manifestSegments, locale, defaultLocale).sort((a, b) => a.sortOrder - b.sortOrder);
+    const effectiveRoutesForLocale = (locale, segmentsForEffectiveLocale) => {
+        // Collect the identities of the effective segments, then allow ANY
+        // segment hash that shares one of those identities. This ensures
+        // default-locale routes (e.g. landing pages) whose segment was
+        // shadowed by a locale-specific segment with the same identity are
+        // still included. When a fallback route points at the shadowed segment
+        // hash, rewrite it to the effective segment hash so routeContext can
+        // recover the translated product/version/tab chrome from the compact
+        // pointer's deduped segment list.
+        const effectiveSegmentByIdentity = new Map(segmentsForEffectiveLocale.map((segment) => [ledgerSegmentIdentity(segment), segment]));
+        const effectiveSegmentHashBySegmentHash = new Map();
+        for (const seg of manifestSegments) {
+            const effective = effectiveSegmentByIdentity.get(ledgerSegmentIdentity(seg));
+            if (effective != null) {
+                effectiveSegmentHashBySegmentHash.set(seg.segmentHash, effective.segmentHash);
+            }
+        }
+        const addRoute = (path, route, out) => {
+            const effectiveSegmentHash = effectiveSegmentHashBySegmentHash.get(route.segmentHash);
+            if (effectiveSegmentHash != null) {
+                out[path] =
+                    effectiveSegmentHash === route.segmentHash
+                        ? route
+                        : {
+                            ...route,
+                            segmentHash: effectiveSegmentHash,
+                            sidebarKey: effectiveSegmentHash
+                        };
+            }
+        };
+        const routes = {};
+        const fallbackRoutes = routesByLocale[defaultLocale] ?? {};
+        for (const [path, route] of Object.entries(fallbackRoutes)) {
+            addRoute(path, route, routes);
+        }
+        const requestedRoutes = routesByLocale[locale] ?? {};
+        for (const [path, route] of Object.entries(requestedRoutes)) {
+            addRoute(path, route, routes);
+        }
+        return routes;
+    };
+    /**
+     * API defs for one locale: locale-independent full hashes, plus pruned
+     * blobs from this locale layered over the default locale's (so endpoints
+     * with no translated artifact still resolve to the base content).
+     */
+    const apiDefsForLocale = (locale) => {
+        const fallbackPruned = prunedHashesByLocale[defaultLocale] ?? {};
+        const localePruned = prunedHashesByLocale[locale] ?? {};
+        const apiDefinitionIds = new Set([
+            ...Object.keys(apiDefs),
+            ...Object.keys(fallbackPruned),
+            ...Object.keys(localePruned)
+        ]);
+        const result = {};
+        for (const apiDefinitionId of apiDefinitionIds) {
+            const base = apiDefs[apiDefinitionId];
+            result[apiDefinitionId] = {
+                ...base,
+                hash: base?.hash ?? "",
+                contentType: base?.contentType ?? "application/json",
+                prunedHashes: {
+                    ...(fallbackPruned[apiDefinitionId] ?? {}),
+                    ...(localePruned[apiDefinitionId] ?? {})
+                }
+            };
+        }
+        return result;
+    };
+    const effectivePagesForLocale = (locale) => ({
+        ...(pagesByLocale[defaultLocale] ?? {}),
+        ...(pagesByLocale[locale] ?? {})
+    });
+    const jsonBlob = (value) => {
+        const bytes = Buffer.from(stableStringify(value), "utf-8");
+        return {
+            hash: stableHash(value),
+            bytes,
+            contentType: "application/json"
+        };
+    };
+    const generatedText = (hash) => {
+        if (hash == null) {
+            return undefined;
+        }
+        return baseResult.generatedBlobs.get(hash)?.bytes.toString("utf-8");
+    };
+    const header = generatedText(baseResult.headerHash);
+    const footer = generatedText(baseResult.footerHash);
+    const cssInline = generatedText(baseResult.cssInlineHash);
+    const jsInline = generatedText(baseResult.jsInlineHash);
+    const configJson = baseResult.configJson ?? null;
+    const configWithInlineChrome = configJson == null ? null : structuredClone(configJson);
+    if (configWithInlineChrome != null) {
+        const configRecord = configWithInlineChrome;
+        if (header != null) {
+            configRecord.header = header;
+        }
+        if (footer != null) {
+            configRecord.footer = footer;
+        }
+        if (cssInline != null) {
+            const css = configRecord.css ?? {};
+            configRecord.css = { ...css, inline: cssInline.split("\n") };
+        }
+        if (jsInline != null) {
+            const js = configRecord.js ?? {};
+            configRecord.js = { ...js, inline: jsInline.split("\n") };
+        }
+    }
+    const localeConfigs = buildLocaleConfigOverrides(configJson, inlineTranslations);
+    const config = {
+        version: baseResult.version ?? null,
+        ...(baseResult.git != null
+            ? {
+                git: {
+                    repoUrl: baseResult.git.repoUrl,
+                    branch: baseResult.git.branch,
+                    ...(baseResult.git.commitSha != null ? { commitSha: baseResult.git.commitSha } : {})
+                }
+            }
+            : {}),
+        config: configWithInlineChrome,
+        ...(localeConfigs != null ? { localeConfigs } : {}),
+        configRefs: {
+            ...(baseResult.headerHash != null && header == null
+                ? {
+                    header: {
+                        hash: baseResult.headerHash,
+                        contentType: "text/markdown"
+                    }
+                }
+                : {}),
+            ...(baseResult.footerHash != null && footer == null
+                ? {
+                    footer: {
+                        hash: baseResult.footerHash,
+                        contentType: "text/markdown"
+                    }
+                }
+                : {}),
+            ...(baseResult.cssInlineHash != null && cssInline == null
+                ? {
+                    cssInline: {
+                        hash: baseResult.cssInlineHash,
+                        contentType: "text/css"
+                    }
+                }
+                : {}),
+            ...(baseResult.jsInlineHash != null && jsInline == null
+                ? {
+                    jsInline: {
+                        hash: baseResult.jsInlineHash,
+                        contentType: "text/javascript"
+                    }
+                }
+                : {}),
+            ...(baseResult.jsFilesHash != null
+                ? {
+                    jsFiles: {
+                        hash: baseResult.jsFilesHash,
+                        contentType: "application/javascript"
+                    }
+                }
+                : {})
+        }
+    };
+    const chrome = { apiNameToId };
+    const blobs = new Map();
+    /** Serialized byte size of a value under the same (stable) rule used to hash it. */
+    const byteSize = (value) => Buffer.byteLength(stableStringify(value), "utf-8");
+    /** Scope key for a segment: identifies its (product, version, variant, tab) navigation scope. */
+    const scopeKeyForSegment = (seg) => `${seg.product?.id ?? ""}|${seg.version?.id ?? ""}|${seg.variant?.id ?? ""}|${seg.tab?.id ?? ""}`;
+    // ── File materialization into shards (ADR 0016) ───────────────────
+    // Files referenced by config (logo/fonts/OG) and navigation chrome
+    // (product images, file:-prefixed product/sidebar icons) are resolved by
+    // the bundle via the pointer's `files` map (`fileMetadata`/`fileArtifact`),
+    // so they are NEVER moved into a shard and NEVER pruned from the pointer.
+    // Everything else a page embeds is materialized into that page's route
+    // shard and dropped from the pointer.
+    const pointerResolvedFilePaths = new Set([
+        ...collectConfigFilePaths((baseResult.configJson ?? {})),
+        ...collectNavigationChromeFilePaths({ segmentDetails, segments, artifacts })
+    ]);
+    const referencedFilesByPageId = args.referencedFilesByPageId ?? {};
+    /** Project a full ManifestFile identity into a lean shard entry (drops domain; bucket only when it diverges). */
+    const toShardFile = (fullPath, mf) => ({
+        hash: mf.hash,
+        fullPath,
+        contentType: mf.contentType,
+        ...(mf.contentLength != null ? { contentLength: mf.contentLength } : {}),
+        ...(mf.width != null ? { width: mf.width } : {}),
+        ...(mf.height != null ? { height: mf.height } : {}),
+        ...(mf.blurDataURL != null ? { blurDataURL: mf.blurDataURL } : {}),
+        ...(mf.bucket !== defaultBucket ? { bucket: mf.bucket } : {})
+    });
+    const pageIdOfRoute = (route) => {
+        const meta = route.artifactMetadata;
+        return typeof meta?.pageId === "string" ? meta.pageId : undefined;
+    };
+    const pointerLocales = {};
+    for (const locale of [...locales].sort()) {
+        const effectiveSegments = segmentsForLocale(locale);
+        const effectiveRoutes = effectiveRoutesForLocale(locale, effectiveSegments);
+        const effectivePages = effectivePagesForLocale(locale);
+        // segmentHash → scopeKey, for every segment in this effective locale.
+        const scopeKeyBySegment = new Map();
+        // scopeKey → segments belonging to that scope (every segment lands in exactly one).
+        const segmentsByScope = new Map();
+        for (const seg of effectiveSegments) {
+            const key = scopeKeyForSegment(seg);
+            scopeKeyBySegment.set(seg.segmentHash, key);
+            (segmentsByScope.get(key) ?? segmentsByScope.set(key, []).get(key)).push(seg);
+        }
+        // scopeKey → routes whose route.segmentHash belongs to a segment in that scope.
+        const routesByScope = new Map();
+        for (const [fullPath, route] of Object.entries(effectiveRoutes)) {
+            const key = scopeKeyBySegment.get(route.segmentHash);
+            if (key == null) {
+                // Route references a segment outside this effective locale — skip.
+                continue;
+            }
+            (routesByScope.get(key) ?? routesByScope.set(key, {}).get(key))[fullPath] = route;
+        }
+        const scopes = [];
+        for (const [key, segs] of segmentsByScope) {
+            const routes = routesByScope.get(key) ?? {};
+            const sidebars = {};
+            for (const seg of segs) {
+                sidebars[seg.segmentHash] = {
+                    strategy: "inline",
+                    locale: seg.locale,
+                    segmentHash: seg.segmentHash,
+                    routes: navBySegment[seg.segmentHash] ?? []
+                };
+            }
+            const payload = { routes, sidebars };
+            scopes.push({ key, payload, size: byteSize(payload) });
+        }
+        // First-fit-decreasing bin packing: sort scopes largest-first and place
+        // each into the first existing shard it still fits in (measuring the merged
+        // serialized {schema, locale, routes, sidebars}); else open a new shard. A
+        // single scope over the target becomes its own (oversized but sub-1-MB) shard.
+        scopes.sort((a, b) => b.size - a.size);
+        const shardPayloads = [];
+        // scopeKey → shard index, used to populate routing/segmentShard.
+        const shardIndexByScope = new Map();
+        for (const scope of scopes) {
+            let placed = false;
+            for (let i = 0; i < shardPayloads.length; i++) {
+                const merged = {
+                    routes: { ...shardPayloads[i].routes, ...scope.payload.routes },
+                    sidebars: {
+                        ...shardPayloads[i].sidebars,
+                        ...scope.payload.sidebars
+                    }
+                };
+                if (byteSize({
+                    schema: LEDGER_SHARD_SCHEMA_VERSION,
+                    locale,
+                    ...merged
+                }) <= LEDGER_SHARD_TARGET_BYTES) {
+                    shardPayloads[i] = merged;
+                    shardIndexByScope.set(scope.key, i);
+                    placed = true;
+                    break;
+                }
+            }
+            if (!placed) {
+                // New shard (a scope larger than the target lands here alone).
+                shardPayloads.push({
+                    routes: { ...scope.payload.routes },
+                    sidebars: { ...scope.payload.sidebars }
+                });
+                shardIndexByScope.set(scope.key, shardPayloads.length - 1);
+            }
+        }
+        // Emit each shard as a CAS blob; record its hash. Materialize the
+        // page→file join: each shard carries the lean identities of every
+        // (non-config) file its routes embed, resolved from the global `files`
+        // map. Paths placed into a shard are pruned from the pointer below.
+        const shards = [];
+        const localeShardedFilePaths = new Set();
+        for (const payload of shardPayloads) {
+            const shardFiles = {};
+            for (const route of Object.values(payload.routes)) {
+                const pageId = pageIdOfRoute(route);
+                if (pageId == null) {
+                    continue;
+                }
+                for (const fileFullPath of referencedFilesByPageId[pageId] ?? []) {
+                    if (pointerResolvedFilePaths.has(fileFullPath) || shardFiles[fileFullPath] != null) {
+                        continue;
+                    }
+                    const mf = files[fileFullPath];
+                    if (mf == null) {
+                        continue;
+                    }
+                    shardFiles[fileFullPath] = toShardFile(fileFullPath, mf);
+                    localeShardedFilePaths.add(fileFullPath);
+                }
+            }
+            const shardBlob = jsonBlob({
+                schema: LEDGER_SHARD_SCHEMA_VERSION,
+                locale,
+                routes: payload.routes,
+                sidebars: payload.sidebars,
+                // Omit when empty so file-less shards hash identically to before.
+                ...(Object.keys(shardFiles).length > 0 ? { files: shardFiles } : {})
+            });
+            blobs.set(shardBlob.hash, shardBlob);
+            shards.push({ hash: shardBlob.hash });
+        }
+        // Prune the pointer's per-locale `files` map: drop every file that was
+        // relocated into a shard. Config / well-known / API-description /
+        // orphan files are not page-referenced (or are config-excluded), so
+        // they never land in `localeShardedFilePaths` and survive here.
+        const prunedFiles = localeShardedFilePaths.size === 0
+            ? files
+            : Object.fromEntries(Object.entries(files).filter(([fp]) => !localeShardedFilePaths.has(fp)));
+        // routing: fullPath → shard index (via its scope). segmentShard: segmentHash → shard index.
+        const routing = {};
+        for (const [fullPath, route] of Object.entries(effectiveRoutes)) {
+            const key = scopeKeyBySegment.get(route.segmentHash);
+            const idx = key != null ? shardIndexByScope.get(key) : undefined;
+            if (idx != null) {
+                routing[fullPath] = idx;
+            }
+        }
+        const segmentShard = {};
+        for (const seg of effectiveSegments) {
+            const idx = shardIndexByScope.get(scopeKeyForSegment(seg));
+            if (idx != null) {
+                segmentShard[seg.segmentHash] = idx;
+            }
+        }
+        // versionFirstRoute: versionId → first routable fullPath (insertion order).
+        const versionFirstRoute = {};
+        const segmentForHash = new Map(effectiveSegments.map((s) => [s.segmentHash, s]));
+        for (const [fullPath, route] of Object.entries(effectiveRoutes)) {
+            const vid = segmentForHash.get(route.segmentHash)?.version?.id;
+            if (vid != null && versionFirstRoute[vid] == null) {
+                versionFirstRoute[vid] = fullPath;
+            }
+        }
+        // Pages blob (pageId → ManifestPage) — off the hot path; search/batch only.
+        const pagesBlob = jsonBlob(effectivePages);
+        blobs.set(pagesBlob.hash, pagesBlob);
+        // Deduplicate product/version SegmentDetails. A site with hundreds of
+        // segments has only a handful of distinct products/versions; inlining
+        // them per segment duplicated ~282 KB on `astronomer`. Catalog them once
+        // and reference by index from each compact pointer-segment. Dedup by id
+        // (product/version SegmentDetail always carry a stable id).
+        const productCatalog = [];
+        const versionCatalog = [];
+        const productIdxById = new Map();
+        const versionIdxById = new Map();
+        const catalogIndex = (detail, catalog, idxById) => {
+            if (detail == null) {
+                return null;
+            }
+            const existing = idxById.get(detail.id);
+            if (existing != null) {
+                return existing;
+            }
+            const idx = catalog.length;
+            catalog.push(detail);
+            idxById.set(detail.id, idx);
+            return idx;
+        };
+        const compactSegments = effectiveSegments.map((seg) => ({
+            segmentId: seg.segmentId,
+            segmentHash: seg.segmentHash,
+            section: seg.section,
+            locale: seg.locale,
+            sortOrder: seg.sortOrder,
+            hidden: seg.hidden,
+            metadata: seg.metadata,
+            productIdx: catalogIndex(seg.product, productCatalog, productIdxById),
+            versionIdx: catalogIndex(seg.version, versionCatalog, versionIdxById),
+            variant: seg.variant,
+            tab: seg.tab
+        }));
+        pointerLocales[locale] = {
+            segments: compactSegments,
+            productCatalog,
+            versionCatalog,
+            routing,
+            segmentShard,
+            shards,
+            versionFirstRoute,
+            pagesHash: pagesBlob.hash,
+            files: prunedFiles,
+            apiDefs: apiDefsForLocale(locale)
+        };
+    }
+    return {
+        pointer: {
+            schema: LEDGER_MANIFEST_SCHEMA_VERSION,
+            orgId: args.orgId,
+            domain: args.domain,
+            basepath: args.basepath,
+            deploymentId: args.deploymentId,
+            deploymentHash: args.deploymentHash,
+            siteId: args.siteId,
+            assignedAt: args.assignedAt,
+            assignedBy: args.assignedBy,
+            isPreview: args.isPreview,
+            isPrivate: args.isPrivate,
+            askAiEnabled: args.askAiEnabled,
+            ...(args.siblingSites != null ? { siblingSites: args.siblingSites } : {}),
+            defaultLocale,
+            // All file bytes are anchored on the canonical fern domain (ADR
+            // 0010); the lean shard file entries omit `domain` and the read
+            // client rebuilds URLs from this.
+            fileAnchorDomain: fileDomain,
+            config,
+            chrome,
+            locales: pointerLocales
+        },
+        blobs: [...blobs.values()]
+    };
+}
+const LOCALE_CONFIG_OVERRIDE_KEYS = ["announcement", "navbarLinks"];
+function isRecord(value) {
+    return typeof value === "object" && value != null && !Array.isArray(value);
+}
+/**
+ * Diff each translation's config against the base-locale config and keep only
+ * the overlay-translatable chrome fields that actually differ. Returns
+ * `undefined` when no locale diverges so pointers for untranslated sites are
+ * byte-identical to before.
+ */
+function buildLocaleConfigOverrides(baseConfig, inlineTranslations) {
+    const base = isRecord(baseConfig) ? baseConfig : {};
+    const overrides = {};
+    for (const translation of inlineTranslations) {
+        if (!isRecord(translation.configJson)) {
+            continue;
+        }
+        const translated = translation.configJson;
+        const override = {};
+        for (const key of LOCALE_CONFIG_OVERRIDE_KEYS) {
+            const value = translated[key];
+            if (value == null || stableStringify(value) === stableStringify(base[key])) {
+                continue;
+            }
+            override[key] = value;
+        }
+        if (Object.keys(override).length > 0) {
+            overrides[translation.locale] = LedgerLocaleConfigOverrideSchema.parse(override);
+        }
+    }
+    return Object.keys(overrides).length > 0 ? overrides : undefined;
+}
+export function buildLedgerManifest(args) {
+    return buildLedgerReadModel(args).pointer;
+}
+//# sourceMappingURL=buildLedgerManifest.js.map