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

package/dist/docs-ledger/docsPublishTransform.js

@@ -0,0 +1,2136 @@
+/**
+ * Server-side transform: DocsPublishInput → TransformResult
+ *
+ * Entry point: {@link transformPublishInput} takes a wire-format DocsPublishInput
+ * plus an {@link ApiManifest} and returns a {@link TransformResult} — the flat,
+ * hash-addressed entities used by the docs-ledger write pipeline
+ * (see `docsLedgerRouter.ts` finish handler and `DocsLedgerDao.persistDeployment`).
+ *
+ * ## Pipeline overview
+ *
+ * 1. The caller (finish handler) fetches the API manifest blob from CAS and
+ *    parses it into an `ApiManifest` (Record<apiDefinitionId, ApiDefinition>).
+ * 2. `transformPublishInput` creates a {@link TransformContext} and walks the
+ *    V1 navigation tree depth-first via `walkRoot` → `walkProductGroup` →
+ *    `walkVersioned` → `walkTabbed` → `walkSidebarRoot` → `walkSection` /
+ *    `walkApiSection` / `walkChangelog`.
+ * 3. At each leaf, artifact factory methods (`makePageArtifact`,
+ *    `makeEndpointArtifact`, `makeApiArtifact`, `makeLinkArtifact`,
+ *    `makeChangelogEntryArtifact`, `makeOverviewArtifact`) produce
+ *    `CollectedArtifact` entries. API artifacts are pruned inline via
+ *    `pruneApiContent` → `@fern-api/fdr-sdk/api-definition.prune()`.
+ * 4. `createSegment` hashes and stores each segment, then `buildNavEntries`
+ *    computes fullPath routes (including default-elided variants via
+ *    `generateFullPaths`).
+ * 5. `buildResult` collects global content refs and returns the final
+ *    `TransformResult`.
+ *
+ * ## Content model
+ *
+ * - **Pages** arrive as BlobRefs (hash + contentType + contentLength), not
+ *   inline markdown. Resolved via `resolvePageBlobRef`.
+ * - **API definitions** arrive as a parsed manifest. The transform prunes
+ *   each API artifact via `pruneApiContent` and serializes the result as a
+ *   server-generated blob (`trackGeneratedJsonBlob` → `generatedBlobs`).
+ * - **Links** are sidebar-only chrome items; they have no CAS content.
+ * - **Config/files** are pre-extracted BlobRefs stored as deployment-level globals.
+ * - **Redirects** are wired as artifacts (type `"redirect"`) in a dedicated segment.
+ * - All structural entities (segment details, artifacts, segments) are hashed
+ *   inline for CAS dedup. Cross-references use hashes, not array indices.
+ * - Nav entries (routing + sidebar ordering) are built inline as segments
+ *   are created via `buildNavEntries`.
+ */
+import { createHash } from "node:crypto";
+import { ORPCError } from "@orpc/client";
+import { kebabCase } from "es-toolkit/string";
+import { prune } from "../api-definition/index.js";
+import { migrate as FernNavigationMigrate, utils as FernNavigationUtils, Slug as LatestSlug, toDefaultSlug, V1 as V1Runtime } from "../navigation/index.js";
+import { GraphQlTypeCategorySchema } from "../orpc-client/index.js";
+import { hashArtifact, hashSegment, hashSegmentDetail } from "./docsLedgerHash.js";
+import { toBasepathRelative } from "./toBasepathRelative.js";
+/**
+ * Transform a single locale's content into hash-addressed entities ready for persistence.
+ *
+ * @param input - One locale entry (content fields) plus the deployment's `domain`.
+ * @param apiManifest - Parsed API definitions (fetched from CAS by the caller).
+ *   Pass an empty object if there are no API references in the nav tree.
+ */
+export function transformPublishInput(input, apiManifest = {}) {
+    const rawRoot = input.root;
+    if (rawRoot == null) {
+        throw new ORPCError("BAD_REQUEST", { message: "DocsPublishInput.root (V1 RootNode) is required" });
+    }
+    if (!isV1RootNode(rawRoot)) {
+        const got = describeRootDiscriminants(rawRoot);
+        throw new ORPCError("BAD_REQUEST", {
+            message: `DocsPublishInput.root must be a V1 RootNode (type="root", version="v1") but got type="${got.type}", version="${got.version}"`
+        });
+    }
+    const ctx = new TransformContext(input, apiManifest);
+    ctx.walkRoot(rawRoot);
+    return ctx.buildResult(input);
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+/**
+ * The shape check the legacy register flow has always performed on the wire
+ * root: a `type: "root"`, `version: "v1"` discriminated object. The rest of
+ * the V1 tree is intentionally NOT structurally validated here — the wire type
+ * is the same `V1.RootNode` the legacy flow stores/serves, and the walk
+ * tolerates the same variants.
+ */
+function isV1RootNode(value) {
+    return (typeof value === "object" &&
+        value != null &&
+        "type" in value &&
+        "version" in value &&
+        value.type === "root" &&
+        value.version === "v1");
+}
+/** Best-effort read of the `type`/`version` discriminants for error messages. */
+function describeRootDiscriminants(value) {
+    if (typeof value !== "object" || value == null) {
+        return { type: undefined, version: undefined };
+    }
+    return {
+        type: "type" in value ? value.type : undefined,
+        version: "version" in value ? value.version : undefined
+    };
+}
+/**
+ * Extract the individual slug segment from an accumulated slug.
+ *
+ * `basePrefix` handles nodes whose published V1 slug omits the site basepath
+ * (a node with an explicit `slug:` under a product on a basepath site): the
+ * slug still nests under the parent once the basepath is dropped from the
+ * parent, so strip it there rather than returning the whole slug — otherwise
+ * the read side re-applies the scope prefix on top of a slug that already
+ * carries it (`docs/core/core/documentation`).
+ */
+function extractSlugSegment(nodeSlug, parentSlug, basePrefix = "") {
+    if (!parentSlug) {
+        return nodeSlug;
+    }
+    // skipUrlSlug: node shares its parent's slug (e.g. apiReference that
+    // doesn't add a URL segment). Return "" so the section path is not
+    // polluted with the full accumulated slug.
+    if (nodeSlug === parentSlug) {
+        return "";
+    }
+    const prefix = parentSlug + "/";
+    if (nodeSlug.startsWith(prefix)) {
+        return nodeSlug.slice(prefix.length);
+    }
+    const relativeParent = toBasepathRelative(parentSlug, basePrefix);
+    if (relativeParent !== "" && relativeParent !== parentSlug) {
+        if (nodeSlug === relativeParent) {
+            return "";
+        }
+        if (nodeSlug.startsWith(`${relativeParent}/`)) {
+            return nodeSlug.slice(relativeParent.length + 1);
+        }
+    }
+    // Fallback: if the slug isn't accumulated, return as-is
+    return nodeSlug;
+}
+/** Join non-empty path parts with '/'. */
+function joinPath(...parts) {
+    return parts.filter(Boolean).join("/");
+}
+/** Append a slug segment to a parent section path. */
+function appendSectionPath(parent, slug) {
+    if (!slug) {
+        return parent;
+    }
+    return parent ? `${parent}/${slug}` : slug;
+}
+/**
+ * Normalise an INTERNAL (root-relative) link `href` to a slug key, or return
+ * `null` for external / protocol-relative URLs (which can never be a
+ * self-redirect). Used to detect a synthetic link redirect that points at its
+ * OWN key — e.g. a home-product link titled "Astro" whose href `/docs/astro`
+ * kebab-resolves to the key `docs/astro`, which is also the Astro product's
+ * landing slug. Emitting `docs/astro → /docs/astro` both 307-loops and shadows
+ * the real product node, so it must be dropped (the node's `pointsTo` then
+ * resolves the landing). Mirrors the read path's `canonicalSlugKey` normaliser.
+ */
+function internalHrefSlug(href) {
+    // Scheme (`https:`) or protocol-relative (`//host`) URLs are external.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("//")) {
+        return null;
+    }
+    const pathOnly = href.split(/[?#]/)[0] ?? href;
+    return FernNavigationUtils.canonicalSlugKey(pathOnly.replace(/^\/+|\/+$/g, ""));
+}
+/**
+ * Resolve `pointsTo` for a V1 node that has `WithRedirect`.
+ * The CLI always sends `pointsTo: undefined`, so we compute it by traversing
+ * the node's children to find the first visible page slug.
+ */
+function resolvePointsTo(node) {
+    const slug = V1Runtime.followRedirect(node);
+    return slug != null ? String(slug) : undefined;
+}
+/**
+ * Resolve root redirects through the same latest-navigation semantics used by
+ * legacy rendering. V1's helper predates page-level auth handling and can point
+ * at an authed page; `mutableUpdatePointsTo` on the migrated tree skips authed
+ * pages, which is the behavior legacy callers observe.
+ */
+function resolveRootPointsTo(root) {
+    const latestRoot = FernNavigationMigrate.FernNavigationV1ToLatest.create().root(root);
+    FernNavigationUtils.mutableUpdatePointsTo(latestRoot);
+    return latestRoot.pointsTo != null ? V1Runtime.Slug(latestRoot.pointsTo) : undefined;
+}
+const EMPTY_SCOPE = {
+    productHash: undefined,
+    productSlug: undefined,
+    productDefault: false,
+    versionHash: undefined,
+    versionSlug: undefined,
+    versionDefault: false,
+    variantHash: undefined,
+    variantSlug: undefined,
+    variantDefault: false,
+    tabHash: undefined,
+    tabSlug: undefined
+};
+// ── Default-elision route generation ─────────────────────────────────────
+/**
+ * Derive all route fullPaths from a node's V1 accumulated slug.
+ *
+ * The V1 slug is the source of truth for the URL path — it already encodes
+ * the correct structure (including custom slug overrides and sections that
+ * don't contribute to child URLs). This function strips known default scope
+ * prefixes (product, version, variant) from the front of the V1 slug, then
+ * generates the power set of elision variants.
+ *
+ * Replaces the previous reconstruction approach ({@link generateFullPaths})
+ * for routing, which broke when `extractSlugSegment` could not strip the
+ * section prefix from a custom-slug page's accumulated path.
+ *
+ * BASEPATH handling (ADR-0014 #6): the `scope.*Slug` entries are basepath-
+ * RELATIVE (e.g. `astro/cli`, `v-1-42` — see `extractSlugSegment`), but the V1
+ * slug is basepath-ABSOLUTE (begins with the deployment basepath, e.g.
+ * `docs/astro/cli/v-1-42/overview`). The prefix checks below match against the
+ * relative scope slugs, so on a `/docs` site the leading basepath would never
+ * match and NO elision variants would be emitted — leaving the default
+ * version's clean URL (`docs/astro/cli/overview`) un-routable (404). To fix
+ * this we strip the basepath off the front first, run the elision power-set on
+ * the basepath-relative remainder, then re-prepend the basepath to every
+ * variant — so the emitted routes stay basepath-ABSOLUTE (matching the `routes`
+ * dict / `routing` table) and carry a single `docs/` prefix. Root sites
+ * (`basePrefix === ""`) are unaffected (the strip/prepend are no-ops).
+ *
+ * This is the WRITE half of the #6 fix; it makes the elided routes resolvable
+ * in the `routing` table so `getScopedRoot`'s `routeContext` can find their
+ * scope. The coordinated READ half lives in `ledger-root-builder.buildVersioned`
+ * (the default version node must carry its full versioned slug so
+ * `NodeCollector`'s default-version pruning emits the elided alias into the nav
+ * `slugMap` that `findNode` gates on).
+ */
+function generateFullPathsFromV1Slug(scope, v1Slug, basePrefix) {
+    const scopePrefixes = [];
+    // The scope slugs are basepath-relative, so strip the basepath off the V1
+    // slug before matching them; we re-prepend it to every emitted variant.
+    let remaining = toBasepathRelative(v1Slug, basePrefix);
+    for (const entry of [
+        { slug: scope.productSlug, isDefault: scope.productDefault },
+        { slug: scope.versionSlug, isDefault: scope.versionDefault },
+        { slug: scope.variantSlug, isDefault: scope.variantDefault }
+    ]) {
+        if (!entry.slug) {
+            continue;
+        }
+        const prefix = entry.slug + "/";
+        if (remaining.startsWith(prefix)) {
+            scopePrefixes.push({ slug: entry.slug, isDefault: entry.isDefault });
+            remaining = remaining.slice(prefix.length);
+        }
+        else if (remaining === entry.slug) {
+            scopePrefixes.push({ slug: entry.slug, isDefault: entry.isDefault });
+            remaining = "";
+            break;
+        }
+        else {
+            break;
+        }
+    }
+    const defaultIndices = scopePrefixes.map((p, i) => (p.isDefault ? i : -1)).filter((i) => i >= 0);
+    if (defaultIndices.length === 0) {
+        return [joinPath(basePrefix, ...scopePrefixes.map((p) => p.slug), remaining)];
+    }
+    const paths = [];
+    for (let mask = 0; mask < 1 << defaultIndices.length; mask++) {
+        const elidedSet = new Set();
+        for (let j = 0; j < defaultIndices.length; j++) {
+            if (mask & (1 << j)) {
+                elidedSet.add(defaultIndices[j]);
+            }
+        }
+        const kept = scopePrefixes.filter((_, i) => !elidedSet.has(i)).map((p) => p.slug);
+        paths.push(joinPath(basePrefix, ...kept, remaining));
+    }
+    return paths;
+}
+/**
+ * Generate all route fullPaths for an artifact, including default-elided
+ * variants. Products, versions, and variants marked as `default` create
+ * additional routes with their slug prefix omitted -- the power set of
+ * elidable slugs produces all valid path variants.
+ *
+ * @deprecated Prefer {@link generateFullPathsFromV1Slug} for routing. This
+ * function is retained for non-routing uses (link redirect slug computation)
+ * where the decomposed scope + section + artifact structure is needed.
+ */
+function generateFullPaths(scope, sectionPath, artifactSlug) {
+    // Ordered prefix components that may be elidable
+    const prefixes = [];
+    if (scope.productSlug) {
+        prefixes.push({ slug: scope.productSlug, isDefault: scope.productDefault });
+    }
+    if (scope.versionSlug) {
+        prefixes.push({ slug: scope.versionSlug, isDefault: scope.versionDefault });
+    }
+    if (scope.variantSlug) {
+        prefixes.push({ slug: scope.variantSlug, isDefault: scope.variantDefault });
+    }
+    // Fixed suffix: tab + section + artifact slug (never elided)
+    const suffix = joinPath(scope.tabSlug, sectionPath, artifactSlug);
+    const defaultIndices = prefixes.map((p, i) => (p.isDefault ? i : -1)).filter((i) => i >= 0);
+    if (defaultIndices.length === 0) {
+        return [joinPath(...prefixes.map((p) => p.slug), suffix)];
+    }
+    // Power set over default indices
+    const paths = [];
+    for (let mask = 0; mask < 1 << defaultIndices.length; mask++) {
+        const elidedSet = new Set();
+        for (let j = 0; j < defaultIndices.length; j++) {
+            if (mask & (1 << j)) {
+                elidedSet.add(defaultIndices[j]);
+            }
+        }
+        const kept = prefixes.filter((_, i) => !elidedSet.has(i)).map((p) => p.slug);
+        paths.push(joinPath(...kept, suffix));
+    }
+    return paths;
+}
+// ── Transform context ────────────────────────────────────────────────────
+class TransformContext {
+    segmentDetails = [];
+    artifacts = [];
+    segments = [];
+    nav = [];
+    siteProducts = [];
+    apiDefinitions = [];
+    contentRefs = new Map();
+    generatedBlobs = new Map();
+    fileEntries = [];
+    /** Dedup file entries by (hash, fullPath) — see {@link TransformFileEntry}. */
+    fileEntryKeys = new Set();
+    /** Segment hashes in creation order, for deploymentSegments. */
+    segmentOrder = [];
+    /**
+     * Every real (non-link) routable `fullPath` emitted by any segment.
+     * Synthetic `link:` redirects are skipped when they collide with one of
+     * these so a real page always wins (write-side dedup, ADR 0013).
+     */
+    realRoutePaths = new Set();
+    /**
+     * Synthetic `link:` redirects collected during the walk, materialised in
+     * {@link buildResult} once `realRoutePaths` is complete.
+     */
+    linkRedirectCandidates = [];
+    structuralRedirectCandidates = [];
+    segmentDetailHashSet = new Set();
+    artifactHashSet = new Set();
+    apiDefIdSet = new Set();
+    pages;
+    apiManifest;
+    locale;
+    assetDomain;
+    /**
+     * The deployment basepath — the V1 root node's slug, which seeds every
+     * accumulated node slug (so real-route `fullPath`s are basepath-ABSOLUTE).
+     * Set once in {@link walkRoot}. Synthetic `link:` redirect keys, whose
+     * parent slug is reconstructed basepath-RELATIVE via {@link generateFullPaths},
+     * are prefixed with this so they match the absolute route keys / `routing`
+     * table (see {@link collectSegmentLinkRedirects}).
+     */
+    basePrefix = "";
+    rootPointsTo;
+    /**
+     * Default-version slug elisions collected during the walk, used to
+     * canonicalise the SITE-ROOT structural-redirect target (Postman
+     * root-redirect regression; sibling to #13147, #12417). Each
+     * entry maps a default version's full accumulated slug (`from`, e.g.
+     * `latest-v-12` or `docs/latest-v-12`) to the parent scope prefix it should
+     * collapse to (`to`, the enclosing product slug or the deployment basepath).
+     *
+     * A versioned site's default version can be reached versionlessly (the read
+     * path's `toDefaultSlug` / `markDefaultVersionCanonicalSlugs` elision), so
+     * the redirect that serves the site root (`/`) must point at that versionless
+     * target — otherwise a derived default-version slug (no explicit `slug:`)
+     * leaks into the root redirect (`/ → /latest-v-12`) and every version switch
+     * from there carries the bad segment. Applied ONLY to the site-root source
+     * (`fullPath === basePrefix`) in {@link flushStructuralRedirects}; scoped
+     * (product/version/variant) redirect targets keep their full non-elided slug,
+     * matching the read-side canonical convention (default product retained,
+     * default version elided).
+     */
+    defaultVersionElisions = [];
+    constructor(input, apiManifest) {
+        this.pages = input.pages;
+        this.apiManifest = apiManifest;
+        this.locale = input.locale ?? "en";
+        this.assetDomain = input.fileDomain ?? input.domain;
+    }
+    // ── Generated blob tracking ─────────────────────────────────────
+    /** Hash and track a JSON-serializable value as a generated blob for CAS upload. */
+    trackGeneratedJsonBlob(value) {
+        const json = JSON.stringify(value);
+        const bytes = Buffer.from(json, "utf-8");
+        const hash = createHash("sha256").update(bytes).digest("hex");
+        if (!this.generatedBlobs.has(hash)) {
+            this.generatedBlobs.set(hash, {
+                ref: { hash, contentType: "application/json", contentLength: bytes.byteLength },
+                bytes
+            });
+        }
+        return { hash, contentType: "application/json", contentLength: bytes.byteLength };
+    }
+    /**
+     * Hash and track a raw text value as a generated blob for CAS upload.
+     *
+     * Used for the four config fields extracted by ADR 0009 (`header`,
+     * `footer`, joined `css.inline`, joined `js.inline`) which are raw
+     * MDX / CSS / JS strings, not JSON. Stored with `contentType: text/plain`
+     * — the loader treats them as opaque byte streams.
+     */
+    trackGeneratedTextBlob(value) {
+        const bytes = Buffer.from(value, "utf-8");
+        const hash = createHash("sha256").update(bytes).digest("hex");
+        if (!this.generatedBlobs.has(hash)) {
+            this.generatedBlobs.set(hash, {
+                ref: { hash, contentType: "text/plain", contentLength: bytes.byteLength },
+                bytes
+            });
+        }
+        return { hash, contentType: "text/plain", contentLength: bytes.byteLength };
+    }
+    /**
+     * Prune a full API definition for a single node and return a real BlobRef.
+     * The pruned JSON bytes are tracked in `generatedBlobs` for the router to upload.
+     */
+    pruneApiContent(apiDefinitionId, node) {
+        const fullDef = this.apiManifest[apiDefinitionId];
+        if (fullDef == null) {
+            // API definition not in manifest — no content to prune.
+            // This happens when the CLI publishes without an apiManifest (e.g. the
+            // initial ledger integration that doesn't yet bundle API definitions).
+            return null;
+        }
+        return this.trackGeneratedJsonBlob(prune(fullDef, node));
+    }
+    /**
+     * Serialize a full API definition and track as a generated blob.
+     * Returns the content BlobRef for the deployment → API definition join.
+     */
+    serializeApiDefinition(apiDefinitionId) {
+        const fullDef = this.apiManifest[apiDefinitionId];
+        if (fullDef == null) {
+            return null;
+        }
+        return this.trackGeneratedJsonBlob(fullDef);
+    }
+    // ── Deduplicating adders ──────────────────────────────────────────
+    /**
+     * Deduplicate and store a segment detail (product, version, variant, or tab).
+     * Returns the content-addressed hash used as a foreign key in segments.
+     */
+    addSegmentDetail(detail) {
+        const hash = hashSegmentDetail({
+            type: detail.type,
+            displayName: detail.displayName,
+            icon: detail.icon,
+            sortOrder: detail.sortOrder,
+            metadata: detail.metadata,
+            hidden: detail.hidden,
+            viewers: detail.viewers,
+            orphaned: detail.orphaned,
+            featureFlags: detail.featureFlags
+        });
+        if (!this.segmentDetailHashSet.has(hash)) {
+            this.segmentDetailHashSet.add(hash);
+            this.segmentDetails.push({ hash, ...detail });
+        }
+        return hash;
+    }
+    /**
+     * Deduplicate and store an artifact (page, API endpoint, link, changelog
+     * entry, file, image, etc.). For CAS-backed content, tracks the BlobRef
+     * for upload routing. For file/image artifacts, the caller passes
+     * `fileKey` instead — those bytes go to the docs bucket, not CAS.
+     *
+     * Exactly one of `content` and `fileKey` should be non-null for
+     * content-bearing artifacts; both are null for link artifacts.
+     *
+     * Returns the content-addressed artifact hash.
+     */
+    addArtifact(artifact) {
+        const contentHash = artifact.content?.hash ?? null;
+        const fileKey = artifact.fileKey ?? null;
+        // Identity hash must distinguish artifacts that resolve to different
+        // bytes. We feed the CAS hash for content-backed artifacts and the
+        // file hash for file-backed ones (they're both SHA-256 of the bytes,
+        // just stored in different tables). For file artifacts, also include
+        // `assetDomain` and `fullPath` — the same bytes at different paths or
+        // canonical upload domains produce different docs-bucket keys and so
+        // must produce different artifacts (the FK points at one specific
+        // (domain, hash, fullPath) row).
+        const identityContentHash = fileKey != null ? `file:${this.assetDomain}|${fileKey.hash}|${fileKey.fullPath}` : contentHash;
+        const hash = hashArtifact({
+            type: artifact.type,
+            hidden: artifact.hidden,
+            metadata: artifact.metadata,
+            contentHash: identityContentHash
+        });
+        if (!this.artifactHashSet.has(hash)) {
+            const { content: _content, fileKey: _inputFileKey, ...artifactFields } = artifact;
+            this.artifactHashSet.add(hash);
+            this.artifacts.push({
+                hash,
+                ...artifactFields,
+                contentHash: fileKey != null ? null : contentHash,
+                fileKey
+            });
+        }
+        // Track content reference for CAS — only for CAS-backed artifacts.
+        // File/image artifacts land in the docs bucket and are tracked via
+        // `fileEntries` instead (see {@link addFileEntry}).
+        if (fileKey == null && artifact.content != null && artifact.content.hash !== "") {
+            this.contentRefs.set(artifact.content.hash, artifact.content);
+        }
+        return hash;
+    }
+    /**
+     * Record a file manifest entry for the register/finish handlers.
+     * Deduped by `(hash, fullPath)` — the same file at the same path is a
+     * single docs_ledger_file row regardless of how many places reference it.
+     */
+    addFileEntry(entry) {
+        const key = `${entry.hash}|${entry.fullPath}`;
+        if (this.fileEntryKeys.has(key)) {
+            return;
+        }
+        this.fileEntryKeys.add(key);
+        this.fileEntries.push(entry);
+    }
+    /**
+     * Register an API definition for the deployment → API definition join table.
+     * Serializes the full definition as a generated blob (deduplicated by ID).
+     */
+    trackApiDefinition(apiDefinitionId) {
+        if (this.apiDefIdSet.has(apiDefinitionId)) {
+            return;
+        }
+        this.apiDefIdSet.add(apiDefinitionId);
+        // Serialize the full API definition for the deployment join
+        const ref = this.serializeApiDefinition(apiDefinitionId);
+        if (ref != null) {
+            const apiName = this.apiManifest[apiDefinitionId]?.apiName ?? null;
+            this.apiDefinitions.push({ apiDefinitionId, apiName, contentHash: ref.hash });
+            this.contentRefs.set(ref.hash, ref);
+        }
+    }
+    // ── Segment creation ──────────────────────────────────────────────
+    /**
+     * Hash and store a segment — a group of artifacts scoped by product/version/variant/tab
+     * at a given section path. Delegates to {@link buildNavEntries} for routing and sidebar
+     * ordering, and records the segment in deployment order.
+     */
+    createSegment(scope, sectionPath, metadata, collected, hidden) {
+        const artifactHashes = collected.map((a) => a.artifactHash);
+        const displaySortOrder = collected.map((a, order) => ({
+            artifactHash: a.artifactHash,
+            displaySortOrder: a.childPosition ?? order
+        }));
+        // Compute routes (skip link artifacts — they're sidebar-only chrome).
+        // First-writer-wins: when a fullPath is already claimed by a
+        // previously-walked segment (e.g. a parent section's overview), skip
+        // the duplicate so the DAO's LIMIT 1 lookup always returns the
+        // canonical artifact.
+        //
+        // Sidebar paths: even when an artifact's routes are all deduped
+        // (another segment already claimed the same fullPaths), the sidebar
+        // entry still needs a fullPath so the nav link renders the correct
+        // href instead of falling back to "/". This matches v2 behavior
+        // where multiple nav nodes could share the same target URL.
+        const routes = [];
+        const sidebarPaths = new Map();
+        for (const a of collected) {
+            if (a.isLink) {
+                continue;
+            }
+            const paths = a.v1Slug != null
+                ? generateFullPathsFromV1Slug(scope, a.v1Slug, this.basePrefix)
+                : generateFullPaths(scope, FernNavigationUtils.stripSyntheticSegments(sectionPath), a.slug);
+            if (paths.length > 0 && !sidebarPaths.has(a.artifactHash)) {
+                sidebarPaths.set(a.artifactHash, paths[0]);
+            }
+            for (const fullPath of paths) {
+                if (this.realRoutePaths.has(fullPath)) {
+                    continue;
+                }
+                routes.push({ artifactHash: a.artifactHash, fullPath });
+                this.realRoutePaths.add(fullPath);
+            }
+        }
+        const segmentHash = hashSegment({
+            locale: this.locale,
+            productHash: scope.productHash,
+            versionHash: scope.versionHash,
+            variantHash: scope.variantHash,
+            tabHash: scope.tabHash,
+            section: sectionPath,
+            metadata,
+            hidden,
+            artifactHashes,
+            displaySortOrder,
+            routes
+        });
+        this.segments.push({
+            hash: segmentHash,
+            locale: this.locale,
+            productHash: scope.productHash,
+            versionHash: scope.versionHash,
+            variantHash: scope.variantHash,
+            tabHash: scope.tabHash,
+            section: sectionPath,
+            metadata,
+            hidden
+        });
+        // Build nav entries inline
+        this.buildNavEntries(segmentHash, collected, routes, sidebarPaths);
+        // Collect synthetic `link:` redirects for this segment. The read path
+        // historically synthesised `<closest-parent-with-slug>/kebab(title)` →
+        // href by walking the reconstructed tree (`collectLinkRedirects`); we
+        // compute the same slug here so the route is byte-identical.
+        // Materialisation (with real-page-wins dedup) is deferred to
+        // `buildResult` once every real route is known.
+        this.collectSegmentLinkRedirects(segmentHash, scope, sectionPath, collected);
+        this.segmentOrder.push(segmentHash);
+    }
+    /**
+     * Compute the segment's reconstructed node slug — the
+     * `closest-parent-with-slug` a `link:` child resolves against in
+     * `collectLinkRedirects` over the read-side reconstructed tree
+     * (`ledger-root-builder`). Returns the parent slug basepath-RELATIVE
+     * (reconstructed from scope/section slugs, which never carry the basepath);
+     * {@link collectSegmentLinkRedirects} prefixes `basePrefix` to make the
+     * final redirect key absolute and line up with `routeContext` lookups.
+     *
+     * - **Sectioned segment** (`sectionPath !== ""`): the section node's slug,
+     *   which the builder takes as the overview route's `fullPath` when an
+     *   overview exists, else the bare section path
+     *   (`ledger-root-builder.sectionNode`).
+     * - **tabRoot segment** (`sectionPath === ""`): links live directly under
+     *   the scope's sidebar root, so the closest parent with a slug is the
+     *   enclosing scope node; its slug is the scope's canonical route prefix
+     *   (`generateFullPaths(scope, "", "")[0]`, i.e. no default-elision).
+     */
+    segmentParentSlug(scope, sectionPath, collected) {
+        const cleanPath = FernNavigationUtils.stripSyntheticSegments(sectionPath);
+        if (cleanPath === "") {
+            return generateFullPaths(scope, "", "")[0] ?? "";
+        }
+        const hasOverview = collected.some((a) => !a.isLink && a.slug === "");
+        if (hasOverview) {
+            return generateFullPaths(scope, cleanPath, "")[0] ?? cleanPath;
+        }
+        return cleanPath;
+    }
+    /**
+     * Queue a synthetic `type:"redirect"` route for every `link:` artifact in a
+     * segment. Slug derivation mirrors `collectLinkRedirects` exactly: the
+     * closest parent's slug + `/` + `kebabCase(title)`, then `canonicalSlugKey`
+     * (the read path's percent-decode normaliser). Links with an empty kebab
+     * title contribute no route (matching the read-side guard).
+     */
+    collectSegmentLinkRedirects(segmentHash, scope, sectionPath, collected) {
+        const links = collected.filter((a) => a.isLink && a.linkHref != null);
+        if (links.length === 0) {
+            return;
+        }
+        const parentSlug = this.segmentParentSlug(scope, sectionPath, collected);
+        for (const link of links) {
+            const segment = kebabCase(link.linkTitle ?? "");
+            if (!segment) {
+                continue;
+            }
+            // `parentSlug` is normally basepath-RELATIVE (reconstructed from
+            // scope/section slugs, which don't carry the basepath), but the
+            // root/home product (`slug: /`) leaks the basepath into its scope
+            // slug. Real route keys and the `routing` table are basepath-
+            // ABSOLUTE (derived from each node's V1 accumulated slug, rooted at
+            // `root.slug` = the basepath). Normalise the parent to relative,
+            // then prefix the basepath exactly once so the synthetic redirect
+            // key lines up with both the `routeContext` lookup
+            // (`getLinkRedirectHref` queries the absolute request path) and the
+            // `realRoutePaths` collision check below — otherwise a `/docs`
+            // site's link redirects 404 and the real-page-wins dedup never
+            // fires. Root sites (empty basepath) are unaffected: `joinPath`
+            // drops the empty prefix.
+            const relativeParent = toBasepathRelative(parentSlug, this.basePrefix);
+            const fullPath = FernNavigationUtils.canonicalSlugKey(joinPath(this.basePrefix, relativeParent, segment));
+            // Drop self-referential redirects (`docs/astro → /docs/astro`): they
+            // 307-loop and shadow the real product/version node at that slug.
+            // Without the synthetic row, `getLinkRedirectHref` misses and the
+            // read path falls through to the node's `pointsTo` (its landing).
+            if (internalHrefSlug(link.linkHref) === fullPath) {
+                continue;
+            }
+            this.linkRedirectCandidates.push({
+                segmentHash,
+                fullPath,
+                href: link.linkHref,
+                redirectKind: "link"
+            });
+        }
+    }
+    /**
+     * Emit routable `type:"redirect"` nav rows for every collected
+     * {@link LinkRedirectCandidate}, applying ADR 0013's write-side dedup:
+     *   1. A real page (or file / config-redirect route) at the same `full_path`
+     *      always wins — skip the synthetic redirect.
+     *   2. Among synthetic redirects, first occurrence at a `full_path` wins
+     *      (deterministic, matching `collectLinkRedirects`'s `if (!out.has(...))`).
+     *
+     * Each surviving redirect produces a `type:"redirect"` artifact (no content;
+     * `metadata.href` carries the target) attached to its owning segment via a
+     * routable nav row — so `routeContext` resolves it inline (page:null,
+     * artifactType:"redirect") and the read path issues a 307 to `href`.
+     */
+    makeRedirectArtifact(candidate) {
+        return this.addArtifact({
+            type: "redirect",
+            hidden: true,
+            metadata: stripUndefined({
+                href: candidate.href,
+                redirectKind: candidate.redirectKind,
+                structuralKind: candidate.structuralKind
+            }),
+            content: null
+        });
+    }
+    emitRedirectRoute(candidate) {
+        this.nav.push({
+            segmentHash: candidate.segmentHash,
+            artifactHash: this.makeRedirectArtifact(candidate),
+            fullPath: candidate.fullPath
+        });
+        this.realRoutePaths.add(candidate.fullPath);
+    }
+    /**
+     * Route keys are basepath-absolute. A `pointsTo` computed from a published
+     * V1 slug that omitted the basepath would never match one, silently
+     * dropping the node's structural redirect (its landing 404s), so re-apply
+     * the prefix when it is missing.
+     */
+    absolutizeSlug(slug) {
+        if (this.basePrefix === "" || slug === this.basePrefix || slug.startsWith(`${this.basePrefix}/`)) {
+            return slug;
+        }
+        return joinPath(this.basePrefix, slug);
+    }
+    resolveAbsolutePointsTo(node) {
+        const pointsTo = resolvePointsTo(node);
+        return pointsTo != null ? this.absolutizeSlug(pointsTo) : undefined;
+    }
+    queueStructuralRedirect(scope, v1Slug, href, overrideExistingRoute, structuralKind) {
+        const rawTarget = href != null ? internalHrefSlug(href) : undefined;
+        if (href == null || rawTarget == null) {
+            return;
+        }
+        const target = this.absolutizeSlug(rawTarget);
+        const resolvedHref = target === rawTarget ? href : target;
+        for (const fullPath of generateFullPathsFromV1Slug(scope, v1Slug, this.basePrefix)) {
+            if (target !== fullPath) {
+                this.structuralRedirectCandidates.push({
+                    fullPath,
+                    href: resolvedHref,
+                    overrideExistingRoute,
+                    structuralKind
+                });
+            }
+        }
+    }
+    dropRoutablePath(fullPath) {
+        for (let i = this.nav.length - 1; i >= 0; i--) {
+            const entry = this.nav[i];
+            if (entry.fullPath !== fullPath) {
+                continue;
+            }
+            if (entry.displaySortOrder != null) {
+                entry.fullPath = undefined;
+            }
+            else {
+                this.nav.splice(i, 1);
+            }
+        }
+    }
+    buildRouteToSegmentHash() {
+        const routeToSegmentHash = new Map();
+        for (const entry of this.nav) {
+            if (entry.fullPath != null) {
+                routeToSegmentHash.set(entry.fullPath, entry.segmentHash);
+            }
+        }
+        return routeToSegmentHash;
+    }
+    /**
+     * Collapse default-version slugs out of a SITE-ROOT redirect target so the
+     * `/` redirect points at the versionless canonical path (sibling to #13147). Applied
+     * only to the site-root source; scoped redirect targets keep their full
+     * slug. Idempotent when the target is already elided (`toDefaultSlug` is a
+     * no-op once the version prefix is gone), so re-running it on a migrated
+     * `rootPointsTo` that already elided the version does nothing.
+     */
+    canonicalizeRootRedirectTarget(target) {
+        let result = target;
+        for (const { from, to } of this.defaultVersionElisions) {
+            result = toDefaultSlug(LatestSlug(result), LatestSlug(to), LatestSlug(from));
+        }
+        return result;
+    }
+    flushStructuralRedirects() {
+        const emitted = new Set();
+        const routeToSegmentHash = this.buildRouteToSegmentHash();
+        for (const candidate of this.structuralRedirectCandidates) {
+            const rawTarget = internalHrefSlug(candidate.href);
+            // Only the SCOPED aliases (version/product/variant/tab/section) that
+            // land on the site-root source (`fullPath === basePrefix`) get their
+            // target version-elided: they carry a full, non-elided `pointsTo`, so
+            // one elision produces the versionless path. The `"root"` candidate is
+            // skipped — its target (`rootPointsTo`) is ALREADY canonical from the
+            // migrate/pointsTo resolution, and re-eliding it can double-strip when
+            // a non-version segment coincidentally shares the default version's
+            // slug (e.g. a section slug equal to the version slug). Scoped sources
+            // below basepath keep their full slug so version-scoped URLs still
+            // redirect within their own version.
+            const canonicalizeTarget = candidate.fullPath === this.basePrefix && candidate.structuralKind !== "root";
+            const target = rawTarget != null && canonicalizeTarget ? this.canonicalizeRootRedirectTarget(rawTarget) : rawTarget;
+            // A root target that collapses to the root itself is a self-redirect
+            // (e.g. `/ → /latest-v-12` where the default version is elided to the
+            // basepath). Drop it — the versionless route serves the root directly,
+            // or a sibling elided alias fills the slot with a versionless target.
+            if (target != null && target === candidate.fullPath) {
+                continue;
+            }
+            const segmentHash = target != null ? routeToSegmentHash.get(target) : undefined;
+            if (emitted.has(candidate.fullPath) ||
+                segmentHash == null ||
+                (!candidate.overrideExistingRoute && this.realRoutePaths.has(candidate.fullPath))) {
+                continue;
+            }
+            emitted.add(candidate.fullPath);
+            if (candidate.overrideExistingRoute) {
+                this.dropRoutablePath(candidate.fullPath);
+                routeToSegmentHash.delete(candidate.fullPath);
+            }
+            this.emitRedirectRoute({
+                segmentHash,
+                fullPath: candidate.fullPath,
+                // Emit the (possibly elided) target so the 307 Location is
+                // versionless for the site root.
+                href: canonicalizeTarget && target != null ? target : candidate.href,
+                redirectKind: "structural",
+                structuralKind: candidate.structuralKind
+            });
+            routeToSegmentHash.set(candidate.fullPath, segmentHash);
+        }
+    }
+    flushLinkRedirects() {
+        const emitted = new Set();
+        for (const candidate of this.linkRedirectCandidates) {
+            // Real-page-wins: never shadow a routable page/file/config redirect.
+            if (this.realRoutePaths.has(candidate.fullPath)) {
+                continue;
+            }
+            // First synthetic redirect at a given full_path wins.
+            if (emitted.has(candidate.fullPath)) {
+                continue;
+            }
+            emitted.add(candidate.fullPath);
+            this.emitRedirectRoute(candidate);
+        }
+    }
+    /**
+     * Create a route-only segment: artifacts are routable by fullPath but have
+     * no sidebar presence (no displaySortOrder). Used for infrastructure segments
+     * like files that should be findable by path but invisible in nav chrome.
+     */
+    createRouteOnlySegment(metadata, collected) {
+        if (collected.length === 0) {
+            return;
+        }
+        const artifactHashes = collected.map((a) => a.artifactHash);
+        const routes = [];
+        for (const a of collected) {
+            routes.push({ artifactHash: a.artifactHash, fullPath: a.slug });
+            this.realRoutePaths.add(a.slug);
+        }
+        const segmentHash = hashSegment({
+            locale: this.locale,
+            productHash: undefined,
+            versionHash: undefined,
+            variantHash: undefined,
+            tabHash: undefined,
+            section: "",
+            metadata,
+            hidden: true,
+            artifactHashes,
+            displaySortOrder: [],
+            routes
+        });
+        this.segments.push({
+            hash: segmentHash,
+            locale: this.locale,
+            section: "",
+            metadata,
+            hidden: true
+        });
+        // Route-only nav: fullPath set, no displaySortOrder
+        for (const r of routes) {
+            this.nav.push({
+                segmentHash,
+                artifactHash: r.artifactHash,
+                fullPath: r.fullPath
+            });
+        }
+        this.segmentOrder.push(segmentHash);
+    }
+    /**
+     * Build nav entries for a segment. Each artifact gets a sidebar entry
+     * (with displaySortOrder); each route gets a routable entry (with fullPath).
+     * Canonical routes (first per artifact) merge both into a single row.
+     *
+     * @param navPaths - Maps artifactHash → its first computed fullPath (for
+     *   sidebar display), even if that path was deduped from the routes array
+     *   by the cross-segment first-writer-wins guard. This ensures every
+     *   artifact's sidebar entry gets a valid href.
+     *
+     * `sidebarPaths` carries the primary fullPath for each artifact computed
+     * BEFORE first-writer-wins route dedup. When an artifact's routes are all
+     * claimed by a previously-walked segment (e.g. two "Redirects" API
+     * subsections sharing the same endpoint slugs), the sidebar entry still
+     * receives the correct fullPath so the nav link renders the right href
+     * instead of falling back to "/". This matches v2 behavior.
+     */
+    buildNavEntries(segmentHash, collected, routes, sidebarPaths) {
+        // Determine canonical path for each artifact (first route wins)
+        const canonicalPaths = new Map();
+        for (const r of routes) {
+            if (!canonicalPaths.has(r.artifactHash)) {
+                canonicalPaths.set(r.artifactHash, r.fullPath);
+            }
+        }
+        const coveredRoutes = new Set();
+        // Sidebar entries: one per artifact in order.
+        // Canonical routes get both fullPath and displaySortOrder in one row.
+        // When an artifact has no canonical route (all deduped), fall back to
+        // sidebarPaths so the nav link still has the correct href.
+        for (let ai = 0; ai < collected.length; ai++) {
+            const a = collected[ai];
+            const canonicalPath = canonicalPaths.get(a.artifactHash) ?? sidebarPaths.get(a.artifactHash);
+            this.nav.push({
+                segmentHash,
+                artifactHash: a.artifactHash,
+                fullPath: canonicalPath,
+                displaySortOrder: a.childPosition ?? ai
+            });
+            if (canonicalPath != null) {
+                coveredRoutes.add(`${segmentHash}:${a.artifactHash}:${canonicalPath}`);
+            }
+        }
+        // Route-only entries: non-canonical routes not already covered
+        for (const r of routes) {
+            const key = `${segmentHash}:${r.artifactHash}:${r.fullPath}`;
+            if (!coveredRoutes.has(key)) {
+                this.nav.push({
+                    segmentHash,
+                    artifactHash: r.artifactHash,
+                    fullPath: r.fullPath
+                });
+                coveredRoutes.add(key);
+            }
+        }
+    }
+    // ── Artifact factories ────────────────────────────────────────────
+    /**
+     * Resolve a page blob ref from the input's pages map.
+     * Throws if the pageId is not present — callers must supply all referenced pages.
+     */
+    resolvePageBlobRef(pageId) {
+        const ref = this.pages[pageId];
+        if (ref != null) {
+            return ref;
+        }
+        throw new ORPCError("BAD_REQUEST", {
+            message: `Page "${pageId}" is referenced in the nav tree but missing from input.pages`
+        });
+    }
+    makePageArtifact(pageId, node, slugPrefix) {
+        const slug = extractSlugSegment(String(node.slug), slugPrefix);
+        const artifactHash = this.addArtifact({
+            type: "markdown",
+            hidden: node.hidden ?? false,
+            metadata: stripUndefined({
+                title: node.title,
+                slug,
+                icon: node.icon,
+                authed: node.authed,
+                pageId,
+                noindex: node.noindex,
+                viewers: node.viewers,
+                orphaned: node.orphaned,
+                featureFlags: node.featureFlags,
+                availability: node.availability
+            }),
+            content: this.resolvePageBlobRef(pageId)
+        });
+        return { artifactHash, slug, isLink: false, v1Slug: String(node.slug) };
+    }
+    makeOverviewArtifact(pageId, parentNode) {
+        const artifactHash = this.addArtifact({
+            type: "markdown",
+            hidden: parentNode.hidden ?? false,
+            metadata: stripUndefined({
+                title: parentNode.title,
+                slug: "",
+                icon: parentNode.icon,
+                authed: parentNode.authed,
+                pageId,
+                isOverview: true,
+                noindex: parentNode.noindex,
+                viewers: parentNode.viewers,
+                orphaned: parentNode.orphaned,
+                featureFlags: parentNode.featureFlags
+            }),
+            content: this.resolvePageBlobRef(pageId)
+        });
+        // slug "" means the route resolves to the section path itself
+        return { artifactHash, slug: "", isLink: false, v1Slug: String(parentNode.slug) };
+    }
+    /**
+     * Create a CAS artifact for an API node (endpoint, websocket, webhook, grpc, graphql).
+     * All API artifact types share the same structure: extract slug, track API def,
+     * build metadata from the node's common fields + type-specific extras, prune
+     * content. `buildArtifact` receives the common metadata fields and returns the
+     * fully-discriminated `type`/`metadata` pair, so each artifact type's required
+     * metadata is checked against its schema-derived type at the call site.
+     */
+    makeApiArtifact(
+    // `playground` lives on the endpoint/webSocket/apiReference variants but not on
+    // the shared `WithNodeMetadata & WithApiDefinitionId` type, so declare it optionally.
+    node, slugPrefix, buildArtifact, pruneNode) {
+        const slug = extractSlugSegment(String(node.slug), slugPrefix);
+        const apiDefId = String(node.apiDefinitionId);
+        this.trackApiDefinition(apiDefId);
+        const artifactHash = this.addArtifact({
+            ...buildArtifact(stripUndefined({
+                title: node.title,
+                slug,
+                icon: node.icon,
+                authed: node.authed,
+                apiDefinitionId: apiDefId,
+                availability: node.availability,
+                viewers: node.viewers,
+                orphaned: node.orphaned,
+                featureFlags: node.featureFlags,
+                playground: toLedgerPlayground(node.playground),
+                noindex: node.noindex
+            })),
+            hidden: node.hidden ?? false,
+            content: this.pruneApiContent(apiDefId, pruneNode)
+        });
+        return { artifactHash, slug, isLink: false, v1Slug: String(node.slug) };
+    }
+    makeEndpointArtifact(node, slugPrefix, endpointPairKey, isResponseStream) {
+        const resolvedIsResponseStream = isResponseStream ?? node.isResponseStream;
+        const resolvedEndpointPairKey = endpointPairKey ?? node.endpointPairKey;
+        return this.makeApiArtifact(node, slugPrefix, (common) => ({
+            type: "rest",
+            metadata: {
+                ...common,
+                endpointId: String(node.endpointId),
+                method: node.method,
+                ...(resolvedIsResponseStream !== undefined ? { isResponseStream: resolvedIsResponseStream } : {}),
+                ...(resolvedEndpointPairKey != null ? { endpointPairKey: resolvedEndpointPairKey } : {})
+            }
+        }), { type: "endpoint", endpointId: node.endpointId });
+    }
+    makeWebSocketArtifact(node, slugPrefix) {
+        return this.makeApiArtifact(node, slugPrefix, (common) => ({ type: "asyncapi", metadata: { ...common, webSocketId: String(node.webSocketId) } }), { type: "webSocket", webSocketId: node.webSocketId });
+    }
+    makeWebhookArtifact(node, slugPrefix) {
+        return this.makeApiArtifact(node, slugPrefix, (common) => ({
+            type: "webhook",
+            metadata: { ...common, webhookId: String(node.webhookId), method: node.method }
+        }), { type: "webhook", webhookId: node.webhookId });
+    }
+    makeGrpcArtifact(node, slugPrefix) {
+        return this.makeApiArtifact(node, slugPrefix, (common) => ({ type: "grpc", metadata: { ...common, grpcId: String(node.grpcId), method: node.method } }), { type: "grpc", grpcId: node.grpcId });
+    }
+    makeGraphQlArtifact(node, slugPrefix) {
+        // Resolve operationType from the V1 node first, falling back to the
+        // authoritative API definition when the node field is missing at
+        // runtime (e.g. older V1 trees that pre-date the field).
+        const operationType = node.operationType ??
+            this.apiManifest[String(node.apiDefinitionId)]?.graphqlOperations[String(node.graphqlOperationId)]
+                ?.operationType;
+        return this.makeApiArtifact(node, slugPrefix, (common) => ({
+            type: "graphql",
+            metadata: {
+                ...common,
+                graphqlOperationId: String(node.graphqlOperationId),
+                operationType
+            }
+        }), { type: "graphql", graphqlOperationId: node.graphqlOperationId });
+    }
+    makeGraphQlTypeArtifact(node, slugPrefix) {
+        // `typeCategory` cannot be recovered from the API definition — the FDR type
+        // model has no GraphQL kind — and there is no manifest fallback of the sort
+        // `makeGraphQlArtifact` uses for `operationType`. So a missing or misspelled
+        // category has no repair path: reject it here, where the message names the
+        // offending node, rather than letting it reach the ledger and silently drop
+        // the page out of the sidebar at read time (see `apiLeafNodeFromNavRouteInternal`).
+        const typeCategory = GraphQlTypeCategorySchema.safeParse(node.typeCategory);
+        if (!typeCategory.success) {
+            throw new ORPCError("BAD_REQUEST", {
+                message: `graphqlType node "${String(node.slug)}" (typeId "${String(node.typeId)}") has ` +
+                    `an invalid typeCategory ${JSON.stringify(node.typeCategory)}; expected one of ` +
+                    `${GraphQlTypeCategorySchema.options.join(", ")}`
+            });
+        }
+        return this.makeApiArtifact(node, slugPrefix, (common) => ({
+            type: "graphqlType",
+            metadata: {
+                ...common,
+                typeId: String(node.typeId),
+                typeCategory: typeCategory.data
+            }
+        }), { type: "graphqlType", typeId: node.typeId });
+    }
+    makeLinkArtifact(node) {
+        // Links are sidebar-only chrome — no CAS content, just metadata.
+        const artifactHash = this.addArtifact({
+            type: "link",
+            hidden: false,
+            metadata: stripUndefined({
+                title: node.title,
+                slug: "",
+                icon: node.icon,
+                url: String(node.url),
+                target: node.target
+            }),
+            content: null
+        });
+        // Links don't contribute to their own page route (slug is empty), but
+        // they do get a synthetic `type:"redirect"` route emitted at the end of
+        // the walk — see {@link createSegment} / {@link buildResult}.
+        return { artifactHash, slug: "", isLink: true, linkTitle: node.title, linkHref: String(node.url) };
+    }
+    makeChangelogEntryArtifact(node, slugPrefix) {
+        const pageId = String(node.pageId);
+        const slug = extractSlugSegment(String(node.slug), slugPrefix);
+        const artifactHash = this.addArtifact({
+            type: "changelog",
+            hidden: node.hidden ?? false,
+            metadata: stripUndefined({
+                title: node.title,
+                slug,
+                icon: node.icon,
+                authed: node.authed,
+                pageId,
+                noindex: node.noindex,
+                date: node.date,
+                tags: node.tags,
+                viewers: node.viewers,
+                orphaned: node.orphaned,
+                featureFlags: node.featureFlags
+            }),
+            content: this.resolvePageBlobRef(pageId)
+        });
+        return { artifactHash, slug, isLink: false, v1Slug: String(node.slug) };
+    }
+    /**
+     * Create a file or image artifact from a fileManifest entry.
+     * Files use type "file", images (entries with width/height) use type "image".
+     *
+     * File bytes land in the public/private docs bucket (not CAS); the
+     * artifact's `fileKey` resolves to a `docs_ledger_file` row during
+     * publish. The transform also records a {@link TransformFileEntry} so
+     * the register handler can issue presigned upload URLs and the finish
+     * handler can upsert the file row.
+     */
+    makeFileArtifact(fullPath, entry) {
+        const isImage = entry.width != null && entry.height != null;
+        const type = isImage ? "image" : "file";
+        const metadata = {
+            contentType: entry.contentType,
+            contentLength: entry.contentLength,
+            filename: entry.filename,
+            width: entry.width,
+            height: entry.height,
+            blurDataURL: entry.blurDataURL
+        };
+        this.addFileEntry({
+            fullPath,
+            hash: entry.hash,
+            contentType: entry.contentType,
+            contentLength: entry.contentLength,
+            filename: entry.filename,
+            width: entry.width,
+            height: entry.height,
+            blurDataURL: entry.blurDataURL
+        });
+        const artifactHash = this.addArtifact({
+            type,
+            hidden: true,
+            metadata: stripUndefined(metadata),
+            content: null,
+            fileKey: { hash: entry.hash, fullPath }
+        });
+        // slug is the fullPath itself — nav routing uses fullPath directly
+        return { artifactHash, slug: fullPath, isLink: false };
+    }
+    // ── Tree walking ──────────────────────────────────────────────────
+    //
+    // Depth-first walk of the V1 nav tree. Each level refines the Scope
+    // (product → version → variant → tab) and accumulates artifacts into
+    // segments. The walk order matches sidebar display order.
+    /** Entry point: walk the root node and dispatch to its single child. */
+    walkRoot(root) {
+        const slugPrefix = String(root.slug);
+        // The root slug IS the deployment basepath; remember it so synthetic
+        // link-redirect keys can be made absolute to match real route keys.
+        this.basePrefix = slugPrefix;
+        this.rootPointsTo = root.pointsTo ?? resolveRootPointsTo(root);
+        this.queueStructuralRedirect({ ...EMPTY_SCOPE }, slugPrefix, this.rootPointsTo, false, "root");
+        this.walkRootChild(root.child, { ...EMPTY_SCOPE }, slugPrefix);
+    }
+    walkRootChild(child, scope, slugPrefix) {
+        switch (child.type) {
+            case "productgroup":
+                this.walkProductGroup(child, scope, slugPrefix);
+                break;
+            case "versioned":
+                this.walkVersioned(child, scope, slugPrefix);
+                break;
+            case "unversioned":
+                this.walkUnversioned(child, scope, slugPrefix);
+                break;
+        }
+    }
+    /** Walk a product group: create segment details per product, recurse into each product's children. */
+    walkProductGroup(node, scope, slugPrefix) {
+        // Landing page at the product group level -- uses tabRoot segment type
+        if (node.landingPage) {
+            const artifacts = [this.makePageArtifact(String(node.landingPage.pageId), node.landingPage, slugPrefix)];
+            this.createSegment(scope, "", { type: "tabRoot", landingPage: true }, artifacts, false);
+        }
+        for (let i = 0; i < node.children.length; i++) {
+            const product = node.children[i];
+            if (product.hidden !== true) {
+                this.siteProducts.push(stripUndefined({
+                    title: product.title,
+                    href: product.type === "productLink" ? String(product.href) : `/${String(product.slug)}/`,
+                    subtitle: product.subtitle !== "" ? product.subtitle : undefined
+                }));
+            }
+            if (product.type === "productLink") {
+                // External product -- create segment detail for chrome (product switcher)
+                // and a marker segment so the detail is discoverable via the
+                // segment→detail join in the read path.
+                const detailHash = this.addSegmentDetail({
+                    type: "product",
+                    displayName: product.title,
+                    icon: product.icon,
+                    sortOrder: i,
+                    metadata: stripUndefined({
+                        default: product.default,
+                        subtitle: product.subtitle,
+                        href: String(product.href),
+                        target: product.target,
+                        image: product.image ? String(product.image) : undefined
+                    }),
+                    hidden: product.hidden ?? false,
+                    viewers: product.viewers?.map(String) ?? [],
+                    orphaned: product.orphaned ?? false,
+                    featureFlags: []
+                });
+                const markerScope = {
+                    ...scope,
+                    productHash: detailHash,
+                    productSlug: undefined,
+                    productDefault: product.default
+                };
+                this.createSegment(markerScope, "", { type: "productLink" }, [], product.hidden ?? false);
+                continue;
+            }
+            const individualSlug = extractSlugSegment(String(product.slug), slugPrefix, this.basePrefix);
+            const detailHash = this.addSegmentDetail({
+                type: "product",
+                displayName: product.title,
+                icon: product.icon,
+                sortOrder: i,
+                metadata: stripUndefined({
+                    slug: individualSlug,
+                    default: product.default,
+                    subtitle: product.subtitle,
+                    image: product.image ? String(product.image) : undefined,
+                    announcementText: product.announcement?.text,
+                    pointsTo: this.resolveAbsolutePointsTo(product)
+                }),
+                hidden: product.hidden ?? false,
+                viewers: product.viewers?.map(String) ?? [],
+                orphaned: product.orphaned ?? false,
+                featureFlags: product.featureFlags?.map(String) ?? []
+            });
+            const productScope = {
+                ...scope,
+                productHash: detailHash,
+                productSlug: individualSlug,
+                productDefault: product.default
+            };
+            this.queueStructuralRedirect(productScope, String(product.slug), this.resolveAbsolutePointsTo(product), true, "product");
+            this.walkProductChild(product.child, productScope, String(product.slug));
+        }
+        if (node.changelog) {
+            this.walkChangelog(node.changelog, scope, slugPrefix, "");
+        }
+    }
+    walkProductChild(child, scope, slugPrefix) {
+        switch (child.type) {
+            case "versioned":
+                this.walkVersioned(child, scope, slugPrefix);
+                break;
+            case "unversioned":
+                this.walkUnversioned(child, scope, slugPrefix);
+                break;
+        }
+    }
+    /** Walk a versioned node: create segment details per version, handle landing pages, recurse. */
+    walkVersioned(node, scope, slugPrefix) {
+        for (let i = 0; i < node.children.length; i++) {
+            const version = node.children[i];
+            const individualSlug = extractSlugSegment(String(version.slug), slugPrefix, this.basePrefix);
+            const detailHash = this.addSegmentDetail({
+                type: "version",
+                displayName: version.title,
+                icon: version.icon,
+                sortOrder: i,
+                metadata: stripUndefined({
+                    slug: individualSlug,
+                    default: version.default,
+                    availability: version.availability,
+                    announcementText: version.announcement?.text,
+                    pointsTo: this.resolveAbsolutePointsTo(version)
+                }),
+                hidden: version.hidden ?? false,
+                viewers: version.viewers?.map(String) ?? [],
+                orphaned: version.orphaned ?? false,
+                featureFlags: version.featureFlags?.map(String) ?? []
+            });
+            const versionScope = {
+                ...scope,
+                versionHash: detailHash,
+                versionSlug: individualSlug,
+                versionDefault: version.default
+            };
+            // Record the default version's slug elision so the site-root
+            // redirect target collapses to the versionless path (sibling to #13147).
+            // `slugPrefix` is the enclosing scope (product slug or deployment
+            // basepath), which is exactly the replacement `toDefaultSlug` uses.
+            if (version.default) {
+                this.defaultVersionElisions.push({ from: String(version.slug), to: slugPrefix });
+            }
+            if (!version.landingPage) {
+                this.queueStructuralRedirect(versionScope, String(version.slug), this.resolveAbsolutePointsTo(version), true, "version");
+            }
+            // Version-level landing page -- uses tabRoot segment type
+            if (version.landingPage) {
+                const artifacts = [
+                    this.makePageArtifact(String(version.landingPage.pageId), version.landingPage, String(version.slug))
+                ];
+                this.createSegment(versionScope, "", { type: "tabRoot", landingPage: true }, artifacts, false);
+            }
+            this.walkVersionChild(version.child, versionScope, String(version.slug));
+        }
+    }
+    walkUnversioned(node, scope, slugPrefix) {
+        if (node.landingPage) {
+            const artifacts = [this.makePageArtifact(String(node.landingPage.pageId), node.landingPage, slugPrefix)];
+            this.createSegment(scope, "", { type: "tabRoot", landingPage: true }, artifacts, false);
+        }
+        this.walkVersionChild(node.child, scope, slugPrefix);
+    }
+    walkVersionChild(child, scope, slugPrefix) {
+        switch (child.type) {
+            case "tabbed":
+                this.walkTabbed(child, scope, slugPrefix);
+                break;
+            case "sidebarRoot":
+                this.walkSidebarRoot(child, scope, slugPrefix);
+                break;
+            case "varianted":
+                this.walkVarianted(child, scope, slugPrefix);
+                break;
+        }
+    }
+    /** Walk a tabbed node: create segment details per tab, handle tab-level links and changelogs. */
+    walkTabbed(node, scope, slugPrefix) {
+        for (let i = 0; i < node.children.length; i++) {
+            const tabChild = node.children[i];
+            switch (tabChild.type) {
+                case "tab": {
+                    const individualSlug = extractSlugSegment(String(tabChild.slug), slugPrefix, this.basePrefix);
+                    const detailHash = this.addSegmentDetail({
+                        type: "tab",
+                        displayName: tabChild.title,
+                        icon: tabChild.icon,
+                        sortOrder: i,
+                        metadata: stripUndefined({
+                            slug: individualSlug,
+                            pointsTo: this.resolveAbsolutePointsTo(tabChild),
+                            tab_type: "tab"
+                        }),
+                        hidden: tabChild.hidden ?? false,
+                        viewers: tabChild.viewers?.map(String) ?? [],
+                        orphaned: tabChild.orphaned ?? false,
+                        featureFlags: tabChild.featureFlags?.map(String) ?? []
+                    });
+                    const tabScope = {
+                        ...scope,
+                        tabHash: detailHash,
+                        tabSlug: individualSlug
+                    };
+                    // A skip-slug tab (slug === enclosing slug) shares the base
+                    // path with its sibling tabs and the root. It must NOT emit a
+                    // route-OVERRIDING redirect there: doing so drops a real page
+                    // that legitimately lives at that path (e.g. the first tab's
+                    // landing / root overview). Use a non-destructive redirect so
+                    // it only fills the base path when nothing real occupies it.
+                    // Tabs that contribute their own slug segment keep the
+                    // overriding behavior (their tab-root is theirs to claim).
+                    this.queueStructuralRedirect(tabScope, String(tabChild.slug), this.resolveAbsolutePointsTo(tabChild), String(tabChild.slug) !== slugPrefix, "tab");
+                    this.walkSidebarRoot(tabChild.child, tabScope, String(tabChild.slug));
+                    break;
+                }
+                case "link": {
+                    // Tab-level link -- no sidebar content, just a detail for the chrome
+                    // and a marker segment so the detail is discoverable via the
+                    // segment→detail join in the read path.
+                    const linkDetailHash = this.addSegmentDetail({
+                        type: "tab",
+                        displayName: tabChild.title,
+                        icon: tabChild.icon,
+                        sortOrder: i,
+                        metadata: stripUndefined({
+                            url: String(tabChild.url),
+                            target: tabChild.target,
+                            tab_type: "link"
+                        }),
+                        hidden: false,
+                        viewers: [],
+                        orphaned: false,
+                        featureFlags: []
+                    });
+                    const linkTabScope = { ...scope, tabHash: linkDetailHash };
+                    this.createSegment(linkTabScope, "", { type: "tabLink" }, [], false);
+                    break;
+                }
+                case "changelog": {
+                    const individualSlug = extractSlugSegment(String(tabChild.slug), slugPrefix, this.basePrefix);
+                    const detailHash = this.addSegmentDetail({
+                        type: "tab",
+                        displayName: tabChild.title,
+                        icon: tabChild.icon,
+                        sortOrder: i,
+                        metadata: stripUndefined({
+                            slug: individualSlug,
+                            pointsTo: this.resolveAbsolutePointsTo(tabChild),
+                            tab_type: "changelog"
+                        }),
+                        hidden: tabChild.hidden ?? false,
+                        viewers: tabChild.viewers?.map(String) ?? [],
+                        orphaned: tabChild.orphaned ?? false,
+                        featureFlags: tabChild.featureFlags?.map(String) ?? []
+                    });
+                    const tabScope = {
+                        ...scope,
+                        tabHash: detailHash,
+                        tabSlug: individualSlug
+                    };
+                    // See the skip-slug rationale in the "tab" case above.
+                    this.queueStructuralRedirect(tabScope, String(tabChild.slug), this.resolveAbsolutePointsTo(tabChild), String(tabChild.slug) !== slugPrefix, "tab");
+                    this.walkChangelog(tabChild, tabScope, String(tabChild.slug), "");
+                    break;
+                }
+            }
+        }
+    }
+    // ── Variant walking ──────────────────────────────────────────────
+    /**
+     * Walk a varianted node (used both at version-level and inside sidebars).
+     * Each variant becomes a segment detail + scoped child walk.
+     */
+    walkVarianted(node, scope, slugPrefix) {
+        for (let i = 0; i < node.children.length; i++) {
+            const variant = node.children[i];
+            const individualSlug = extractSlugSegment(String(variant.slug), slugPrefix, this.basePrefix);
+            const detailHash = this.addSegmentDetail({
+                type: "variant",
+                displayName: variant.title,
+                icon: variant.icon,
+                sortOrder: i,
+                metadata: stripUndefined({
+                    slug: individualSlug,
+                    default: variant.default,
+                    subtitle: variant.subtitle,
+                    image: variant.image ? String(variant.image) : undefined,
+                    pointsTo: this.resolveAbsolutePointsTo(variant)
+                }),
+                hidden: variant.hidden ?? false,
+                viewers: variant.viewers?.map(String) ?? [],
+                orphaned: variant.orphaned ?? false,
+                featureFlags: variant.featureFlags?.map(String) ?? []
+            });
+            const variantScope = {
+                ...scope,
+                variantHash: detailHash,
+                variantSlug: individualSlug,
+                variantDefault: variant.default
+            };
+            this.queueStructuralRedirect(variantScope, String(variant.slug), this.resolveAbsolutePointsTo(variant), true, "variant");
+            this.walkVariantChildren(variant.children, variantScope, String(variant.slug));
+        }
+    }
+    walkVariantChildren(children, scope, slugPrefix) {
+        // Pass 1: collect leaf artifacts (pages, links; recurse into sidebar groups).
+        // Use a running offset so childPosition is globally unique across
+        // sidebarGroups (same fix as walkSidebarRoot).
+        const rootArtifacts = [];
+        let offset = 0;
+        for (const child of children) {
+            switch (child.type) {
+                case "page": {
+                    const a = this.makePageArtifact(String(child.pageId), child, slugPrefix);
+                    a.childPosition = offset;
+                    rootArtifacts.push(a);
+                    offset++;
+                    break;
+                }
+                case "link": {
+                    const a = this.makeLinkArtifact(child);
+                    a.childPosition = offset;
+                    rootArtifacts.push(a);
+                    offset++;
+                    break;
+                }
+                case "sidebarGroup": {
+                    const leaves = this.collectNavLeaves(child.children, slugPrefix);
+                    for (const leaf of leaves) {
+                        if (leaf.childPosition != null) {
+                            leaf.childPosition += offset;
+                        }
+                    }
+                    rootArtifacts.push(...leaves);
+                    offset += child.children.length;
+                    break;
+                }
+                default:
+                    offset++;
+                    break;
+            }
+        }
+        if (rootArtifacts.length > 0) {
+            this.createSegment(scope, "", stripUndefined({
+                type: "tabRoot",
+                pointsTo: scope.productHash == null &&
+                    scope.versionHash == null &&
+                    scope.variantHash == null &&
+                    scope.tabHash == null
+                    ? this.rootPointsTo
+                    : undefined
+            }), rootArtifacts, false);
+        }
+        // Pass 2: walk sub-trees (sections, API refs, changelogs; recurse into sidebar groups).
+        // sidebarDepth=0 marks these as root-level peers so the read side
+        // does not infer parent-child relationships from slug prefixes.
+        //
+        // Direct children (not in a sidebarGroup) with skipUrlSlug
+        // (slug === parent slug) must keep childIndex=undefined so the
+        // read-side hasTrueRootWrapper detection is preserved. Non-skip
+        // children get the global offset for correct interleaving.
+        offset = 0;
+        for (const child of children) {
+            switch (child.type) {
+                case "section": {
+                    const skip = String(child.slug) === slugPrefix;
+                    this.walkSection(child, scope, slugPrefix, "", skip ? undefined : offset, 0);
+                    offset++;
+                    break;
+                }
+                case "apiReference": {
+                    const skip = String(child.slug) === slugPrefix;
+                    this.walkApiSection(child, scope, slugPrefix, "", skip ? undefined : offset, 0);
+                    offset++;
+                    break;
+                }
+                case "changelog":
+                    this.walkChangelog(child, scope, slugPrefix, "");
+                    offset++;
+                    break;
+                case "sidebarGroup":
+                    this.walkNavSubTrees(child.children, scope, slugPrefix, "", 0, offset);
+                    offset += child.children.length;
+                    break;
+                default:
+                    offset++;
+                    break;
+            }
+        }
+    }
+    // ── Sidebar walking ───────────────────────────────────────────────
+    /**
+     * Walk the sidebar root: two-pass approach ensures the root segment is
+     * created before child segments (correct sidebar ordering).
+     */
+    walkSidebarRoot(node, scope, slugPrefix) {
+        // Pass 1: collect leaf artifacts from sidebar groups. Sidebar roots
+        // cannot contain pages/links directly in V1, but sidebar-group leaves
+        // still belong to the root segment and participate in root redirect
+        // behavior.
+        //
+        // When non-collapsible sections sit between sidebarGroups at the
+        // sidebarRoot level, groupSidebarRootChildren splits pages into
+        // multiple sidebarGroups. Each group's collectNavLeaves resets
+        // childPosition to 0, causing displaySortOrder collisions in the
+        // tabRoot segment. Track a running offset so every child gets a
+        // globally-unique position that the read-side interleave can sort.
+        const rootArtifacts = [];
+        let offset = 0;
+        for (const child of node.children) {
+            if (child.type === "sidebarGroup") {
+                const leaves = this.collectNavLeaves(child.children, slugPrefix);
+                for (const leaf of leaves) {
+                    if (leaf.childPosition != null) {
+                        leaf.childPosition += offset;
+                    }
+                }
+                rootArtifacts.push(...leaves);
+                offset += child.children.length;
+            }
+            else {
+                offset++;
+            }
+        }
+        if (rootArtifacts.length > 0) {
+            this.createSegment(scope, "", stripUndefined({
+                type: "tabRoot",
+                pointsTo: scope.productHash == null &&
+                    scope.versionHash == null &&
+                    scope.variantHash == null &&
+                    scope.tabHash == null
+                    ? this.rootPointsTo
+                    : undefined
+            }), rootArtifacts, false);
+        }
+        // Pass 2: walk sub-trees in child order with global offsets so
+        // section childIndex values align with the leaf displaySortOrder
+        // values from Pass 1, enabling correct interleaving on the read side.
+        offset = 0;
+        for (const child of node.children) {
+            switch (child.type) {
+                case "sidebarGroup":
+                    this.walkNavSubTrees(child.children, scope, slugPrefix, "", 0, offset);
+                    offset += child.children.length;
+                    break;
+                case "section": {
+                    const skip = String(child.slug) === slugPrefix;
+                    this.walkSection(child, scope, slugPrefix, "", skip ? undefined : offset, 0);
+                    offset++;
+                    break;
+                }
+                case "apiReference": {
+                    const skip = String(child.slug) === slugPrefix;
+                    this.walkApiSection(child, scope, slugPrefix, "", skip ? undefined : offset, 0);
+                    offset++;
+                    break;
+                }
+                case "varianted":
+                    this.walkVarianted(child, scope, slugPrefix);
+                    offset++;
+                    break;
+            }
+        }
+    }
+    /** Collect leaf artifacts (pages, links) from navigation children, tracking position. */
+    collectNavLeaves(children, slugPrefix, overviewPageId) {
+        const artifacts = [];
+        for (let i = 0; i < children.length; i++) {
+            const child = children[i];
+            switch (child.type) {
+                case "page": {
+                    const pageId = String(child.pageId);
+                    if (overviewPageId != null && pageId === overviewPageId) {
+                        break;
+                    }
+                    const a = this.makePageArtifact(pageId, child, slugPrefix);
+                    a.childPosition = i;
+                    artifacts.push(a);
+                    break;
+                }
+                case "link": {
+                    const a = this.makeLinkArtifact(child);
+                    a.childPosition = i;
+                    artifacts.push(a);
+                    break;
+                }
+            }
+        }
+        return artifacts;
+    }
+    /** Walk sub-tree navigation children (sections, API refs, changelogs, variants). */
+    walkNavSubTrees(children, scope, slugPrefix, parentSectionPath, sidebarDepth, childIndexOffset) {
+        const base = childIndexOffset ?? 0;
+        for (let i = 0; i < children.length; i++) {
+            const child = children[i];
+            switch (child.type) {
+                case "section":
+                    this.walkSection(child, scope, slugPrefix, parentSectionPath, base + i, sidebarDepth);
+                    break;
+                case "apiReference":
+                    this.walkApiSection(child, scope, slugPrefix, parentSectionPath, base + i, sidebarDepth);
+                    break;
+                case "changelog":
+                    this.walkChangelog(child, scope, slugPrefix, parentSectionPath, undefined, base + i);
+                    break;
+                case "varianted":
+                    this.walkVarianted(child, scope, slugPrefix);
+                    break;
+            }
+        }
+    }
+    /** Walk a section: collect overview + leaf children, create segment, then walk sub-trees. */
+    walkSection(node, scope, slugPrefix, parentSectionPath, childIndex, sidebarDepth) {
+        const individualSlug = extractSlugSegment(String(node.slug), slugPrefix);
+        const effectiveSlug = individualSlug === "" && childIndex != null
+            ? `${FernNavigationUtils.SKIP_URL_SLUG_PREFIX}${childIndex}`
+            : individualSlug;
+        const sectionPath = appendSectionPath(parentSectionPath, effectiveSlug);
+        const currentPrefix = String(node.slug);
+        const pointsTo = node.pointsTo != null ? String(node.pointsTo) : resolvePointsTo(node);
+        this.queueStructuralRedirect(scope, String(node.slug), pointsTo, false, "section");
+        const ovPageId = node.overviewPageId ? String(node.overviewPageId) : undefined;
+        // Overview occupies position -1 so it sorts before children (whose
+        // childPosition starts at 0) without colliding in displaySortOrder.
+        const sectionArtifacts = [
+            ...(ovPageId != null ? [{ ...this.makeOverviewArtifact(ovPageId, node), childPosition: -1 }] : []),
+            ...this.collectNavLeaves(node.children, currentPrefix, ovPageId)
+        ];
+        const hasSubTrees = node.children.some((c) => c.type === "section" || c.type === "apiReference" || c.type === "changelog");
+        if (sectionArtifacts.length > 0 || hasSubTrees) {
+            this.createSegment(scope, sectionPath, stripUndefined({
+                type: "section",
+                title: node.title,
+                icon: node.icon,
+                authed: node.authed,
+                collapsed: node.collapsed,
+                collapsible: node.collapsible,
+                collapsedByDefault: node.collapsedByDefault,
+                availability: node.availability,
+                overviewPageId: node.overviewPageId ? String(node.overviewPageId) : undefined,
+                noindex: node.noindex,
+                pointsTo,
+                childIndex,
+                sidebarDepth,
+                viewers: node.viewers,
+                orphaned: node.orphaned,
+                featureFlags: node.featureFlags
+            }), sectionArtifacts, node.hidden ?? false);
+        }
+        const nextDepth = sidebarDepth != null ? sidebarDepth + 1 : undefined;
+        this.walkNavSubTrees(node.children, scope, currentPrefix, sectionPath, nextDepth);
+    }
+    // ── API reference / package walking ───────────────────────────────
+    /**
+     * Walk an API reference or API package node. Both share the same structure:
+     * compute section path, track API def, collect overview + leaf children,
+     * create segment, then walk sub-packages and changelog.
+     */
+    walkApiSection(node, scope, slugPrefix, parentSectionPath, childIndex, sidebarDepth) {
+        const individualSlug = extractSlugSegment(String(node.slug), slugPrefix);
+        const effectiveSlug = individualSlug === "" && childIndex != null
+            ? `${FernNavigationUtils.SKIP_URL_SLUG_PREFIX}${childIndex}`
+            : individualSlug;
+        const sectionPath = appendSectionPath(parentSectionPath, effectiveSlug);
+        const currentPrefix = String(node.slug);
+        this.trackApiDefinition(String(node.apiDefinitionId));
+        const pointsTo = node.pointsTo != null ? String(node.pointsTo) : resolvePointsTo(node);
+        this.queueStructuralRedirect(scope, String(node.slug), pointsTo, false, "api-section");
+        // Pass 1: collect leaf API artifacts (endpoints, webhooks, etc.)
+        const artifacts = [];
+        const ovPageId = node.overviewPageId ? String(node.overviewPageId) : undefined;
+        if (ovPageId != null) {
+            // Overview occupies position -1 so it sorts before children (whose
+            // childPosition starts at 0) without colliding in displaySortOrder.
+            artifacts.push({ ...this.makeOverviewArtifact(ovPageId, node), childPosition: -1 });
+        }
+        for (let i = 0; i < node.children.length; i++) {
+            const child = node.children[i];
+            switch (child.type) {
+                case "endpoint":
+                    artifacts.push({ ...this.makeEndpointArtifact(child, currentPrefix), childPosition: i });
+                    break;
+                case "endpointPair": {
+                    const pairKey = String(child.nonStream.endpointId);
+                    artifacts.push({
+                        ...this.makeEndpointArtifact(child.nonStream, currentPrefix, pairKey, false),
+                        childPosition: i
+                    });
+                    artifacts.push({
+                        ...this.makeEndpointArtifact(child.stream, currentPrefix, pairKey, true),
+                        childPosition: i
+                    });
+                    break;
+                }
+                case "webSocket":
+                    artifacts.push({ ...this.makeWebSocketArtifact(child, currentPrefix), childPosition: i });
+                    break;
+                case "webhook":
+                    artifacts.push({ ...this.makeWebhookArtifact(child, currentPrefix), childPosition: i });
+                    break;
+                case "grpc":
+                    artifacts.push({ ...this.makeGrpcArtifact(child, currentPrefix), childPosition: i });
+                    break;
+                case "graphql":
+                    artifacts.push({ ...this.makeGraphQlArtifact(child, currentPrefix), childPosition: i });
+                    break;
+                case "graphqlType":
+                    artifacts.push({ ...this.makeGraphQlTypeArtifact(child, currentPrefix), childPosition: i });
+                    break;
+                case "page": {
+                    const pageId = String(child.pageId);
+                    if (ovPageId != null && pageId === ovPageId) {
+                        break;
+                    }
+                    artifacts.push({
+                        ...this.makePageArtifact(pageId, child, currentPrefix),
+                        childPosition: i
+                    });
+                    break;
+                }
+                case "link":
+                    artifacts.push({ ...this.makeLinkArtifact(child), childPosition: i });
+                    break;
+            }
+        }
+        const metadata = stripUndefined({
+            type: node.type,
+            title: node.title,
+            icon: node.icon,
+            authed: node.authed,
+            collapsed: node.collapsed,
+            apiDefinitionId: String(node.apiDefinitionId),
+            overviewPageId: node.overviewPageId ? String(node.overviewPageId) : undefined,
+            noindex: node.noindex,
+            availability: node.availability,
+            pointsTo,
+            childIndex,
+            sidebarDepth,
+            viewers: node.viewers,
+            orphaned: node.orphaned,
+            featureFlags: node.featureFlags,
+            playground: toLedgerPlayground(node.playground),
+            // ApiReference-specific fields (undefined values stripped for apiPackage)
+            ...(node.type === "apiReference"
+                ? { paginated: node.paginated, showErrors: node.showErrors, hideTitle: node.hideTitle }
+                : {})
+        });
+        const hasApiPackageChildren = node.children.some((c) => c.type === "apiPackage");
+        const hasChangelog = node.type === "apiReference" && node.changelog != null;
+        if (artifacts.length > 0 || hasApiPackageChildren || hasChangelog) {
+            this.createSegment(scope, sectionPath, metadata, artifacts, node.hidden ?? false);
+        }
+        // Pass 2: walk sub-packages (the only sub-tree in API packages)
+        const nextDepth = sidebarDepth != null ? sidebarDepth + 1 : undefined;
+        for (let i = 0; i < node.children.length; i++) {
+            const child = node.children[i];
+            if (child.type === "apiPackage") {
+                this.walkApiSection(child, scope, currentPrefix, sectionPath, i, nextDepth);
+            }
+        }
+        if (node.type === "apiReference" && node.changelog) {
+            this.walkChangelog(node.changelog, scope, currentPrefix, sectionPath, String(node.apiDefinitionId));
+        }
+    }
+    // ── Changelog walking ─────────────────────────────────────────────
+    /** Walk a changelog: flatten year/month/entry hierarchy into a single segment. */
+    walkChangelog(node, scope, slugPrefix, parentSectionPath, apiDefinitionId, childIndex) {
+        const individualSlug = extractSlugSegment(String(node.slug), slugPrefix);
+        const sectionPath = appendSectionPath(parentSectionPath, individualSlug);
+        const currentPrefix = String(node.slug);
+        const artifacts = [];
+        // Overview page — position -1 so it sorts before entries without
+        // colliding in displaySortOrder (entries start at 0).
+        if (node.overviewPageId) {
+            artifacts.push({ ...this.makeOverviewArtifact(String(node.overviewPageId), node), childPosition: -1 });
+        }
+        // Flatten year/month/entry hierarchy. Each entry gets an explicit
+        // childPosition so displaySortOrder doesn't rely on array-index
+        // fallback — keeps ordering deterministic across re-publishes.
+        let entryPos = 0;
+        for (const year of node.children) {
+            for (const month of year.children) {
+                for (const entry of month.children) {
+                    artifacts.push({
+                        ...this.makeChangelogEntryArtifact(entry, currentPrefix),
+                        childPosition: entryPos
+                    });
+                    entryPos++;
+                }
+            }
+        }
+        if (artifacts.length > 0) {
+            this.createSegment(scope, sectionPath, stripUndefined({
+                type: "changelog",
+                title: node.title,
+                icon: node.icon,
+                overviewPageId: node.overviewPageId ? String(node.overviewPageId) : undefined,
+                noindex: node.noindex,
+                authed: node.authed,
+                viewers: node.viewers,
+                orphaned: node.orphaned,
+                featureFlags: node.featureFlags,
+                apiDefinitionId,
+                childIndex
+            }), artifacts, node.hidden ?? false);
+        }
+    }
+    // ── Final assembly ───────────────────────────────────────────────
+    /**
+     * Build the TransformResult from collected structural data.
+     * Collects global content refs and assembles deployment segments.
+     */
+    buildResult(input) {
+        // ADR 0009: split the config into (a) structural JSONB inlined on
+        // the deployment row, and (b) four extracted content rows for the
+        // variable-length fields (`header`, `footer`, `css.inline`,
+        // `js.inline`). ADR 0016 re-inlines those text fields into the S3
+        // pointer so site chrome does not add page-render reads.
+        let configJson;
+        let headerBlobRef;
+        let footerBlobRef;
+        let cssInlineBlobRef;
+        let jsInlineBlobRef;
+        if (input.config != null) {
+            const { stripped, header, footer, cssInline, jsInline } = splitConfig(input.config);
+            configJson = { ...stripped, rootSlug: this.basePrefix };
+            if (header !== undefined) {
+                headerBlobRef = this.trackGeneratedTextBlob(header);
+            }
+            if (footer !== undefined) {
+                footerBlobRef = this.trackGeneratedTextBlob(footer);
+            }
+            if (cssInline !== undefined) {
+                cssInlineBlobRef = this.trackGeneratedTextBlob(cssInline);
+            }
+            if (jsInline !== undefined) {
+                jsInlineBlobRef = this.trackGeneratedTextBlob(jsInline);
+            }
+        }
+        else {
+            configJson = { rootSlug: this.basePrefix };
+        }
+        // Track global content refs (files, jsFiles, apiManifest)
+        for (const ref of [input.jsFiles, input.apiManifest]) {
+            if (ref != null) {
+                this.contentRefs.set(ref.hash, ref);
+            }
+        }
+        // Wire redirects as a first-class artifact in a dedicated segment.
+        // The segment uses EMPTY_SCOPE (no product/version/variant/tab) and an
+        // empty section path — no sentinel value is needed because the segment
+        // is identified by its content-addressed hash, which is unique to this
+        // combination of scope, metadata ({ type: "redirects" }), and the
+        // redirect artifact's content hash.
+        if (input.redirects != null) {
+            const redirectsRef = input.redirects;
+            this.contentRefs.set(redirectsRef.hash, redirectsRef);
+            const artifactHash = this.addArtifact({
+                type: "redirect",
+                hidden: true,
+                metadata: {},
+                content: redirectsRef
+            });
+            this.createRouteOnlySegment({ type: "redirects" }, [{ artifactHash, slug: "", isLink: false }]);
+        }
+        // Wire file manifest entries as artifacts in a dedicated "files" segment.
+        // Files are route-only (fullPath set, no displaySortOrder) — they must be
+        // findable by path but must not appear in sidebar navigation or nav chrome.
+        if (input.fileManifest != null) {
+            const entries = Object.entries(input.fileManifest);
+            if (entries.length > 0) {
+                entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+                const fileArtifacts = [];
+                for (const [fullPath, entry] of entries) {
+                    fileArtifacts.push(this.makeFileArtifact(fullPath, entry));
+                }
+                this.createRouteOnlySegment({ type: "files" }, fileArtifacts);
+            }
+        }
+        // Materialise structural redirects before synthetic `link:` redirects.
+        // Structural rows are existing flat routes (`type:"redirect"` artifacts)
+        // for implicit product/version/tab URLs whose legacy pointsTo is derived
+        // from the full navigation tree.
+        this.flushStructuralRedirects();
+        // Materialise synthetic `link:` redirects now that every real route is
+        // known (pages + files + config redirects). ADR 0013: each `link:` node
+        // becomes a routable `type:"redirect"` row at
+        // `<closest-parent-with-slug>/kebab(title)` → href, EXCEPT where a real
+        // page already owns that `full_path` (real-page-wins dedup). Emitted
+        // last so the dedup set is complete.
+        this.flushLinkRedirects();
+        // Track generated blobs as content refs too
+        for (const [hash, blob] of this.generatedBlobs) {
+            this.contentRefs.set(hash, blob.ref);
+        }
+        return {
+            segmentDetails: this.segmentDetails,
+            artifacts: this.artifacts,
+            segments: this.segments,
+            nav: this.nav,
+            deploymentSegments: this.segmentOrder.map((segmentHash, sortOrder) => ({ segmentHash, sortOrder })),
+            apiDefinitions: this.apiDefinitions,
+            siteProducts: this.siteProducts,
+            jsFilesHash: input.jsFiles?.hash,
+            configJson,
+            headerHash: headerBlobRef?.hash,
+            footerHash: footerBlobRef?.hash,
+            cssInlineHash: cssInlineBlobRef?.hash,
+            jsInlineHash: jsInlineBlobRef?.hash,
+            domain: input.domain,
+            fileDomain: input.fileDomain ?? input.domain,
+            version: input.version,
+            repo: input.repo,
+            git: input.git,
+            contentRefs: this.contentRefs,
+            generatedBlobs: this.generatedBlobs,
+            fileEntries: this.fileEntries,
+            referencedFilesByPageId: collectReferencedFilesByPageId(input.pages)
+        };
+    }
+}
+/**
+ * Project the publish input's `pages` map into `pageId → referencedFiles`,
+ * dropping pages with no embedded files (ADR 0016). Keys mirror the `pages`
+ * record's keys (the `pageId`), which is exactly how artifacts carry
+ * `metadata.pageId`, so the read model can join routes to their files.
+ */
+function collectReferencedFilesByPageId(pages) {
+    const out = {};
+    for (const [pageId, page] of Object.entries(pages)) {
+        const refs = page?.referencedFiles;
+        if (refs != null && refs.length > 0) {
+            out[pageId] = refs;
+        }
+    }
+    return out;
+}
+// ── Utility functions ────────────────────────────────────────────────────
+/** Remove keys with undefined values from an object. */
+function stripUndefined(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Coerce a nav node's `playground` (branded Fern types) into the plain ledger
+ * metadata shape written into segment / artifact metadata. `stripUndefined` drops
+ * absent options at runtime, so the resulting object matches the all-optional
+ * schema type — the cast just widens the branded `EnvironmentId`/`Url` to strings.
+ */
+function toLedgerPlayground(pg) {
+    if (pg == null) {
+        return undefined;
+    }
+    return stripUndefined({
+        hidden: pg.hidden,
+        environments: pg.environments,
+        button: pg.button?.href != null ? { href: String(pg.button.href) } : undefined,
+        "limit-websocket-messages-per-connection": pg["limit-websocket-messages-per-connection"],
+        "send-optional-defaults": pg["send-optional-defaults"]
+    });
+}
+/**
+ * Split a {@link LedgerConfig} into the structural portion (to be written
+ * inline as JSONB) and the four variable-length fields that are extracted
+ * to their own CAS blobs (ADR 0009).
+ *
+ * - `header`, `footer`: returned as the raw strings if non-empty.
+ * - `css.inline`, `js.inline`: arrays of strings, joined with `\n` into a
+ *   single text blob if non-empty. The `inline` key is removed from `css`
+ *   and `js` in the stripped config; any other sibling fields (`js.files`,
+ *   `js.remote`) are preserved. `css.inline` is currently the only field
+ *   on `css`, so `stripped.css` is dropped in practice — the empty-keys
+ *   check is kept for symmetry with `js` and to stay correct if the
+ *   schema grows new `css` siblings.
+ *
+ * The returned `stripped` object is a shallow-cloned subset of `config` so
+ * that callers can safely mutate it without affecting the original.
+ *
+ * The input has already been validated against `LedgerConfigSchema` by
+ * Zod upstream — no runtime shape checks are needed here.
+ *
+ * Exported for testing.
+ *
+ * @internal
+ */
+export function splitConfig(config) {
+    const { header: rawHeader, footer: rawFooter, css: rawCss, js: rawJs, ...rest } = config;
+    const stripped = { ...rest };
+    let cssInline;
+    if (rawCss != null) {
+        const { inline, ...cssRest } = rawCss;
+        if (inline != null && inline.length > 0) {
+            cssInline = inline.join("\n");
+        }
+        if (Object.keys(cssRest).length > 0) {
+            stripped.css = cssRest;
+        }
+    }
+    let jsInline;
+    if (rawJs != null) {
+        const { inline, ...jsRest } = rawJs;
+        if (inline != null && inline.length > 0) {
+            jsInline = inline.join("\n");
+        }
+        if (Object.keys(jsRest).length > 0) {
+            stripped.js = jsRest;
+        }
+    }
+    return {
+        stripped,
+        header: rawHeader != null && rawHeader.length > 0 ? rawHeader : undefined,
+        footer: rawFooter != null && rawFooter.length > 0 ? rawFooter : undefined,
+        cssInline,
+        jsInline
+    };
+}
+//# sourceMappingURL=docsPublishTransform.js.map