@roottale/cms-renderer-next 0.47.0 → 0.51.0

package/dist/routes.d.ts

@@ -1,6 +1,7 @@
 import { CmsPostContent, RootTaleRedirect, CmsPostTranslationRef } from '@roottale/cms-client/server';
 import { RouteCollection } from '@roottale/cms-core';
 export { RouteCollection, resolvePostCollection, resolvePostUrl } from '@roottale/cms-core';
+import { B as BlogCategoryWithCount } from './blog-filter-BKCGM0qd.js';
 
 /**
  * `routes` 공통 — config 타입, collections resolve, fetch 헬퍼. feed/sitemap/llms/
@@ -49,23 +50,12 @@ declare function resolveCollections(input: CollectionsInput | undefined): Promis
 declare function trimSlash(u: string): string;
 declare function safeFetchPosts(config: RootTaleSiteConfig, limit: number): Promise<CmsPostContent[]>;
 
-/** `routes` — RSS feed + sitemap 팩토리. collection 모드/레거시 양쪽. */
-
 /**
- * `app/feed.xml/route.ts` 용 GET 핸들러. RSS 2.0.
- *
- * ```ts
- * import { createFeedRoute } from "@roottale/cms-renderer-next/routes";
- * export const dynamic = "force-dynamic";
- * export const GET = createFeedRoute({
- *   apiKey: process.env.ROOTTALE_API_KEY!,
- *   siteUrl: "https://example.com",
- *   title: "Example 블로그",
- *   description: "...",
- * });
- * ```
+ * 사이트맵 entry 조립 — `createSitemap`·`createSitemapIndex` 가 공유하는 내부
+ * 빌더. 라우트 팩토리(`routes-feed-sitemap.ts`)와 분리해 "무엇을 내보낼지"(정책·
+ * 조립)와 "어떤 라우트로 내보낼지"(Next 계약)를 나눈다. 공개 표면은 `routes.ts` 배럴.
  */
-declare function createFeedRoute(config: RootTaleSiteConfig): () => Promise<Response>;
+
 /** Next `MetadataRoute.Sitemap[number]` 와 구조 호환(타입 결합 회피). */
 interface SitemapEntry {
     url: string;
@@ -89,11 +79,38 @@ interface SitemapIndexOptions {
     locales?: string[];
     /** admin 의 `authors` 토글을 덮어쓴다 (작가 사이트맵). */
     authors?: boolean;
+    /**
+     * admin 의 "검색에 이 분류 페이지 노출" 집계를 덮어쓴다 — 색인 정책상 여기
+     * 없는 카테고리의 아카이브는 sitemap 에서 빠진다. `skipRemoteSettings` 와 함께
+     * 쓰면 네트워크 없이 정책을 켤 수 있다(빌드 타임 사이트맵).
+     */
+    promotedCategorySlugs?: string[];
     /** 작가 아카이브 base path. 기본 "/blog/author" (→ /blog/author/{slug}). */
     authorBasePath?: string;
     /** true 면 admin 설정 fetch 생략(opts/기본값만). 빌드 시 네트워크 회피용. */
     skipRemoteSettings?: boolean;
 }
+
+/**
+ * `routes` — RSS feed + sitemap 라우트 팩토리. collection 모드/레거시 양쪽.
+ * 사이트맵 entry 조립(정책·설정 해석)은 `routes-sitemap-entries.ts` 가 맡는다.
+ */
+
+/**
+ * `app/feed.xml/route.ts` 용 GET 핸들러. RSS 2.0.
+ *
+ * ```ts
+ * import { createFeedRoute } from "@roottale/cms-renderer-next/routes";
+ * export const dynamic = "force-dynamic";
+ * export const GET = createFeedRoute({
+ *   apiKey: process.env.ROOTTALE_API_KEY!,
+ *   siteUrl: "https://example.com",
+ *   title: "Example 블로그",
+ *   description: "...",
+ * });
+ * ```
+ */
+declare function createFeedRoute(config: RootTaleSiteConfig): () => Promise<Response>;
 /**
  * @deprecated `createSitemapIndex` 를 쓰세요 — 단일 평면 사이트맵 대신 인덱스 분리
  * (static/blog/categories) + 이미지 + admin 토글을 지원한다. 본 함수는 하위호환용으로
@@ -426,6 +443,20 @@ interface PostMetadataInput {
      * `alternates.languages` 를 계산한다. 없거나 자기 자신 1건뿐이면 languages 생략.
      */
     translations?: readonly CmsPostTranslationRef[];
+    /**
+     * avcd 구조(og article 확장) — 최근 수정 ISO 일시 → `openGraph.modifiedTime`.
+     * `CmsPostContent.updatedAt` 등을 그대로 넘기면 된다. 미지정 시 생략.
+     */
+    modified?: string | null;
+    /** avcd 구조 — 글 섹션/카테고리명 → `openGraph.section`. 미지정 시 생략. */
+    section?: string | null;
+    /** avcd 구조 — 글 태그명 목록 → `openGraph.tags`. 빈 배열/미지정 시 생략. */
+    tags?: readonly string[] | null;
+    /**
+     * avcd 구조 — 저자 프로필 URL 목록 → `openGraph.authors` (Next `Metadata`
+     * article 확장). 빈 배열/미지정 시 생략.
+     */
+    authors?: readonly string[] | null;
 }
 interface BuildPostMetadataOptions {
     /**
@@ -452,6 +483,12 @@ interface BuildPostMetadataOptions {
      * (opt-in — 명시 안 한 기존 소비자는 canonical-only 로 diff 0).
      */
     locales?: PostLocaleOptions;
+    /**
+     * avcd 구조 — RSS 피드 절대 경로 → `alternates.types["application/rss+xml"]`.
+     * 기본 `"/feed.xml"`. `siteUrl` 이 있으면 canonical 유무와 무관하게 항상 emit
+     * (RSS 발견성은 개별 글의 canonical 해석 성공 여부와 무관한 사이트 차원 신호).
+     */
+    feedPath?: string;
 }
 /**
  * ADR-0052 A안 (W4-6 PR C1) — hreflang 경로 계산 옵션. `buildPostMetadata` 와
@@ -467,29 +504,62 @@ interface PostLocaleOptions {
      */
     pathFor?: (locale: string, slug: string) => string;
 }
+/** robots 지시자 — Next `Metadata.robots` 의 구조적 부분집합. */
+interface RobotsMeta {
+    index: boolean;
+    follow: boolean;
+}
+/**
+ * noindex/nofollow 플래그 → `Metadata.robots`. **글과 아카이브가 공유하는 단
+ * 하나의 robots 표현** — 둘 중 한쪽만 형태가 바뀌면 색인 정책이 갈리므로
+ * `buildPostMetadata` 와 `buildArchiveMetadata` 가 이 함수만 쓴다.
+ *
+ * 둘 다 꺼져 있으면 `undefined` — robots 를 아예 emit 하지 않아 검색엔진 기본값
+ * (index, follow)을 그대로 둔다.
+ */
+declare function resolveRobotsMeta(flags: {
+    noindex?: boolean;
+    nofollow?: boolean;
+}): RobotsMeta | undefined;
 /** Next `Metadata` 의 구조적 부분집합 — 소비자는 그대로 return 가능. */
 interface PostMetadata {
     title: string;
     description?: string;
     alternates?: {
-        canonical: string;
+        /** `types` 만 emit 되는 경우(예: siteUrl 만 있고 path/collections 미해석)도 있어 optional. */
+        canonical?: string;
         languages?: Record<string, string>;
+        /** avcd 구조 — RSS 등 대체 표현. Next `Metadata.alternates.types` 그대로. */
+        types?: Record<string, string>;
     };
-    robots?: {
-        index: boolean;
-        follow: boolean;
-    };
+    robots?: RobotsMeta;
     openGraph: {
         type: "article";
         title: string;
         description?: string;
         url?: string;
         publishedTime?: string;
+        /** avcd 구조 — og article 확장. */
+        modifiedTime?: string;
+        section?: string;
+        tags?: string[];
+        authors?: string[];
         images?: {
             url: string;
             alt: string;
         }[];
     };
+    /**
+     * avcd 구조 — Twitter Card. og 와 동일 소스(seo override → 글 값)에서 title/
+     * description/images 를 채운다. `card`+`title` 은 항상 emit(og 이미지 유무와
+     * 무관), `images` 는 og 이미지가 있을 때만.
+     */
+    twitter?: {
+        card: "summary_large_image";
+        title: string;
+        description?: string;
+        images?: string[];
+    };
     /** ADR-0065 — `<meta name="rt:content-id">` 등 임의 head meta (조회수 식별자). */
     other?: Record<string, string>;
 }
@@ -502,6 +572,9 @@ interface PostMetadata {
  *   → 없으면 생략. 모든 글이 자기 자신을 가리키는 canonical 을 갖는 게 권장이므로
  *   `siteUrl` 과 함께 `path` 또는 `collections` 전달을 권장한다.
  * - `noindex`/`nofollow` 중 하나라도 켜지면 `robots` 출력.
+ * - avcd 구조 — `siteUrl` 이 있으면 `alternates.types["application/rss+xml"]`
+ *   (기본 `/feed.xml`, `feedPath` 로 override)을 canonical 유무와 무관하게 emit.
+ *   Twitter Card(`summary_large_image`)는 og 와 같은 소스로 항상 emit.
  *
  * ```ts
  * // 단일 블로그(레거시): 라우트가 곧 섹션이므로 path 를 직접 준다.
@@ -535,6 +608,289 @@ declare function buildPostMetadata(post: PostMetadataInput, options?: BuildPostM
  */
 declare function buildHreflangLanguages(translations: readonly CmsPostTranslationRef[] | undefined, siteUrl: string, locales: PostLocaleOptions): Record<string, string> | undefined;
 
+/**
+ * 아카이브(모음 페이지) 색인 정책 — **단일 SSoT**.
+ *
+ * seo-geo-contract v3.1 §1 "색인 위생": robots 메타(noindex)와 sitemap 포함은
+ * **한 소스에서 파생**해야 한다. 둘이 갈리면 "noindex 인데 sitemap 에 제출된 URL"
+ * 이 생기고, 검색엔진은 이를 크롤 예산 낭비 + 품질 신호 하락으로 취급한다.
+ *
+ * 그래서 이 파일의 `decideArchiveIndex` 하나가
+ * - `routes-sitemap-entries.ts` 의 sitemap entry 필터(`inSitemap`)
+ * - 아카이브 페이지 `generateMetadata` 의 robots(`buildArchiveMetadata` → `index`)
+ * - 0건 아카이브의 404 처리(`render`)
+ * 를 **동시에** 결정한다. 소비처가 따로 판단하지 않는다.
+ *
+ * 정책 요지: 아카이브는 **기본 noindex**. 고유한 소개 글을 채워 "허브"로 승격한
+ * 분류·작가만 색인 대상이 된다(`promotion`).
+ *
+ * **판정 입력도 이 파일에서 만든다**(`resolveCategoryPromotion`·
+ * `resolveAuthorPromotion`). 판정 함수만 공유하고 입력 조립을 소비처가 따로
+ * 하면 "sitemap 은 모름을 통과로, 페이지는 모름을 미승격으로" 읽는 식으로
+ * 결론이 갈린다 — 실제로 그렇게 갈렸던 것이 이 3-state 도입의 계기다.
+ * (같은 이유로 **모집단**도 한 곳에서 정한다 — `archive-categories.ts`.)
+ *
+ * ## 불변식의 범위 — 정상 상태(steady state) 보장이다
+ *
+ * "noindex 인데 sitemap 포함" 이 없다는 계약은 **두 요청이 같은 설정을 봤을 때**
+ * 성립한다. sitemap 과 아카이브 페이지는 서로 다른 요청에서 각자 설정을 조회하고
+ * (sitemap 은 ISR 캐시, 페이지는 요청 시 렌더), 한쪽만 실패할 수 있다. 예를 들어
+ * 페이지 조회는 성공(`promotedCategorySlugs: []` → `not-promoted` → noindex)인데
+ * sitemap 조회는 실패(`undefined` → `unknown` → 포함)면 그 창 동안 두 결론이
+ * 어긋난다. 이건 코드로 없앨 수 없다 — 두 표면이 같은 시점의 설정을 본다고
+ * 보장할 방법이 없기 때문이다(공유 캐시를 둬도 만료 시점이 갈린다).
+ *
+ * **자가 치유 시간 = 사이트맵 revalidate 주기.** 다음 재생성 때 설정을 정상
+ * 조회하면 어긋남이 사라진다. Site Kit(`sites/starter/app/sitemap.ts`)은
+ * `export const revalidate = 60` 이므로 **상한 60초**다(아카이브 페이지도 60초).
+ * 고객 사이트가 값을 바꿨으면 그 값이 곧 상한이다.
+ *
+ * **왜 이 방향인가(sitemap 조회 실패 시 포함 유지)**: 반대로 fail-closed 하면
+ * 일시적 API 장애 한 번에 이미 색인된 URL 이 sitemap 에서 통째로 빠진다 —
+ * 재발견까지 걸리는 노출 손실이 "잠깐 noindex 인 URL 이 sitemap 에 남는" 비용보다
+ * 크다. 후자는 크롤러가 해당 URL 을 방문해 noindex 를 읽고 색인에서 빼는, 되돌릴
+ * 수 있는 낭비다. (작가 **entry** 쪽만 예외로 fail-closed 인데, 이유는
+ * `routes-sitemap-entries.ts` 의 `authorEntries` 주석 참조 — 라우트 자체가 없는
+ * 사이트에 존재하지 않는 URL 을 제출할 위험이 더 크기 때문이다.)
+ *
+ * ## 정책 대상에서 뺀 것 (스펙 예외)
+ *
+ * 분류 **목록** 허브(`/blog/categories`, collection 모드의
+ * `{basePath}/categories`)는 이 정책을 적용하지 않고 항상 sitemap 에 넣는다.
+ * 개별 아카이브가 아니라 "이 사이트에 어떤 분류가 있는지" 를 훑는 **내비게이션
+ * 허브**라, 중복 콘텐츠 위험(같은 글이 여러 모음에 중복 노출)이 없고 크롤러가
+ * 분류 구조를 발견하는 진입점 역할을 하기 때문이다. 정본 스펙(seo-geo-contract
+ * v3.1 §2)에는 이 예외가 아직 명문화돼 있지 않다 — 스펙 개정이 필요하다.
+ */
+
+/** 승격("허브로 올리기") 개념이 있는 아카이브 종류. */
+type PromotableArchiveKind = "category" | "author";
+/** 종류만으로 항상 noindex 인 아카이브 — 승격 개념이 없다. */
+type AlwaysNoindexArchiveKind = "tag" | "date" | "search" | "paginated";
+/** 아카이브 종류. `paginated` 는 종류 불명의 2페이지 이상 목록. */
+type ArchiveKind = PromotableArchiveKind | AlwaysNoindexArchiveKind;
+/**
+ * 허브 승격 상태 — **boolean 이 아니라 3-state 다**.
+ *
+ * - `promoted` — 어드민에서 노출을 켰다(확정).
+ * - `not-promoted` — 켜지 않았다(확정). 아카이브 기본값.
+ * - `unknown` — 승격 설정을 **읽지 못했다**. 구버전 API 응답이라 필드가 없거나,
+ *   설정 fetch 가 실패했거나, 빌드 타임 사이트맵이 설정 조회를 생략한 경우.
+ *
+ * `unknown` 을 `not-promoted` 로 뭉개면 "설정을 못 읽었다" 는 이유만으로 이미
+ * 색인된 URL 에 noindex 를 붙이고 sitemap 에서 지우게 된다 — 근거 없는 노출
+ * 손실이다. 그래서 `unknown` 은 **정책 미적용 = 기존 동작 보존**(색인 + sitemap
+ * 포함)으로 fail-soft 한다. 이 결정을 소비처가 아니라 정책 함수 안에 두는 이유는
+ * 위 모듈 주석 참조.
+ */
+type ArchivePromotion = "promoted" | "not-promoted" | "unknown";
+/**
+ * 아카이브 정책이 `postCount` 를 세는 **폴백 모집단 한도**. sitemap 과 아카이브
+ * 페이지가 이 상수를 함께 import 해 같은 크기의 최근 글 배치에서 개수를 파생한다.
+ * 소비처마다 N 이 다르면 같은 카테고리에 대해 sitemap 은 "글 있음", 페이지는
+ * "0건 → 404" 라는 상충이 생긴다(정확히 이 상수를 만든 이유다).
+ *
+ * **이제는 폴백 경로에서만 쓰인다**: 카테고리 `postCount` 의 1순위 소스는 서버측
+ * 집계 API(`GET /v1/cms/public/categories`)이고, 그쪽은 발행 글 수와 무관하게
+ * 모든 분류의 정확한 개수를 준다. 이 배치 파생은 그 API 를 못 받았을 때
+ * (구버전 API·일시 장애) 기존 동작을 보존하는 fail-soft 경로다 —
+ * `archive-categories.ts` 참조.
+ *
+ * **폴백 경로의 알려진 한계(그대로 유지)**: 발행 글이 이 한도를 넘는 사이트에서는
+ * 한도 밖에만 글이 있는 카테고리가 sitemap·페이지 **양쪽 모두에서** 누락된다
+ * (페이지는 404). 양쪽이 같은 방식으로 틀리므로 색인 위생 계약(noindex ↔ sitemap
+ * 불일치)은 깨지지 않는다.
+ *
+ * collection 모드 스트림 아카이브(`collectCollectionCategories`)는 아직 이 배치
+ * 파생만 쓴다 — 집계 API 는 `collection_key` 스코프를 이미 지원하므로 배선만
+ * 남았다(후속).
+ */
+declare const ARCHIVE_POST_COUNT_LIMIT = 200;
+/** 개수·페이지 입력 — 종류와 무관한 공통 부분. */
+interface ArchiveScopeInput {
+    /**
+     * 이 아카이브에 실제로 걸린 발행 글 수. 0 = 빈 아카이브.
+     * 유한한 0 이상 정수여야 한다(아래 "입력 경계" 참조).
+     */
+    postCount: number;
+    /** 1-base 페이지 번호. 미지정 = 1페이지. 유한한 1 이상 정수여야 한다. */
+    page?: number;
+}
+/**
+ * `decideArchiveIndex` 입력. 종류에 따라 갈리는 판별 유니온이라,
+ * **승격 상태는 의미가 있는 종류에서만 요구되고 나머지에서는 아예 받지 않는다** —
+ * 태그 아카이브에 `promotion` 을 넘겨놓고 반영되길 기대하는 오해를 타입이 막는다.
+ */
+type ArchiveIndexInput = (ArchiveScopeInput & {
+    kind: PromotableArchiveKind;
+    promotion: ArchivePromotion;
+}) | (ArchiveScopeInput & {
+    kind: AlwaysNoindexArchiveKind;
+});
+interface ArchiveIndexDecision {
+    /** `notFound` 면 페이지가 404 를 반환해야 한다(빈 아카이브 = 색인 쓰레기). */
+    render: "ok" | "notFound";
+    /** robots 색인 허용 여부. `buildArchiveMetadata` 가 이 값으로 robots 를 만든다. */
+    index: boolean;
+    /** sitemap 에 이 URL 을 넣을지. `index` 가 false 면 반드시 false. */
+    inSitemap: boolean;
+}
+/**
+ * 카테고리 승격 상태. 소스는 공개 projection
+ * `blog-settings.sitemap.promotedCategorySlugs`(어드민 카테고리 편집의
+ * "검색에 이 분류 페이지 노출" 토글 집계).
+ *
+ * 목록 자체가 `undefined` 면 `unknown` — 빈 배열 `[]`("승격 0건" 확정)과 의미가
+ * 다르다. cms-client `fetchBlogSettings` 가 구버전 응답에서 필드를 **생략**하고,
+ * 설정 fetch 실패 경로도 목록을 만들지 않으므로 이 구분이 그대로 전달된다.
+ */
+declare function resolveCategoryPromotion(promotedSlugs: readonly string[] | undefined, slug: string): ArchivePromotion;
+/**
+ * 작가 승격 상태. 카테고리와 달리 작가는 개별 승격 UI 가 없고 **사이트 단위 토글**
+ * (`blog-settings.sitemap.authors`, "작가별 글 모음도 검색엔진에 알리기")이 곧
+ * 승격 신호다. 토글 값을 못 읽었으면 `undefined` 를 넘겨 `unknown` 을 받는다.
+ */
+declare function resolveAuthorPromotion(authorsEnabled: boolean | undefined): ArchivePromotion;
+/**
+ * 아카이브 URL 하나의 색인·sitemap·렌더 판정. **판정 순서가 곧 정책이다**:
+ *
+ * 0. **입력 경계** — `postCount` 가 유한한 0 이상 정수가 아니거나 `page` 가 유한한
+ *    1 이상 정수가 아니면 noindex + sitemap 제외로 중립 처리한다. 개수를 못 세는
+ *    상태에서 "좋은 모음 페이지" 라고 주장할 근거가 없고, 그렇다고 404 로 화면을
+ *    없애는 것은 과한 파괴라서 **화면은 살리고 색인만 보류**한다.
+ * 1. **0건** (검색 제외) → 404. 빈 모음 페이지는 애초에 존재하면 안 된다.
+ *    검색 결과는 0건이어도 정상 화면이라 404 로 만들지 않는다.
+ * 2. **2페이지 이상** 이거나 **검색·날짜·태그** → noindex + sitemap 제외.
+ *    (승격 여부와 무관 — 승격된 카테고리의 2페이지도 noindex 다.)
+ * 3. **카테고리·작가** → 승격 상태 3-state 로 결정. `promoted` 면 색인 + sitemap,
+ *    `not-promoted` 면 noindex + 제외, `unknown` 이면 정책 미적용(기존 동작 보존).
+ */
+declare function decideArchiveIndex(input: ArchiveIndexInput): ArchiveIndexDecision;
+interface ArchiveMetadataFields {
+    /** 아카이브 화면 제목 (예: "세무 | 블로그"). */
+    title: string;
+    /** 메타 설명 — 분류 소개 글 등. 비면 생략. */
+    description?: string | null;
+    /** 링크 추적 제외. 색인과 별개 축이라 정책이 건드리지 않는다. */
+    nofollow?: boolean;
+}
+type ArchiveMetadataInput = ArchiveIndexInput & ArchiveMetadataFields;
+interface BuildArchiveMetadataOptions {
+    /** self-canonical origin (예: `https://example.com`). `path` 와 함께. */
+    siteUrl?: string;
+    /** self-canonical 경로 (예: `/blog/categories/tax`). `siteUrl` 과 함께. */
+    path?: string;
+}
+/** Next `Metadata` 의 구조적 부분집합 — 아카이브 `generateMetadata` 가 그대로 return. */
+interface ArchiveMetadata {
+    title: string;
+    description?: string;
+    alternates?: {
+        canonical: string;
+    };
+    robots?: RobotsMeta;
+}
+/**
+ * 아카이브 페이지 metadata. **robots 는 `decideArchiveIndex` 의 `index` 에서만**
+ * 파생된다 — sitemap 필터와 같은 판정이라 "noindex 인데 sitemap 에 있음" 이
+ * 구조적으로 불가능하다.
+ *
+ * `render === "notFound"` 판정(0건 아카이브)은 metadata 로 표현할 수 없으므로
+ * 페이지가 `decideArchiveIndex` 를 직접 호출해 `notFound()` 를 부른다:
+ *
+ * ```ts
+ * const promotion = resolveCategoryPromotion(settings.sitemap?.promotedCategorySlugs, slug);
+ * const decision = decideArchiveIndex({ kind: "category", promotion, postCount });
+ * if (decision.render === "notFound") notFound();
+ * // generateMetadata 에서:
+ * return buildArchiveMetadata(
+ *   { kind: "category", promotion, postCount, title: `${name} | 블로그` },
+ *   { siteUrl, path: `/blog/categories/${slug}` },
+ * );
+ * ```
+ */
+declare function buildArchiveMetadata(input: ArchiveMetadataInput, options?: BuildArchiveMetadataOptions): ArchiveMetadata;
+
+/**
+ * 아카이브 카테고리 **모집단** — "이 아카이브 라우트가 실제로 다루는 글 집합" 을
+ * 정하는 단일 지점. 사이트맵과 아카이브 페이지가 **같은 함수**를 호출한다.
+ *
+ * 판정 함수(`decideArchiveIndex`)와 승격 상태 조립(`resolveCategoryPromotion`)을
+ * 공유해도 **세는 글 집합이 다르면** 결론이 갈린다. 실제로 갈렸다:
+ *
+ * - 사이트맵은 발행 글 **전체**에서 카테고리를 셌고,
+ * - `/blog` 계열 아카이브 페이지는 스트림(collection) 소속 글을 뺀 **"미소속 글"**
+ *   만 다룬다(`blog-list-collection-scope.md` §2① — "/blog 계열 표면은 전부
+ *   미소속 글 = 블로그로 통일", `RootTaleBlogList` 의 `excludeCollections`).
+ *
+ * 그래서 스트림 글에만 달린 카테고리(예: `symptoms` 스트림 글 1건뿐인 `symptom`)가
+ * **사이트맵엔 URL 이 있는데 페이지는 404** 인 상충을 만들었다.
+ *
+ * ## 어느 쪽으로 맞췄나 — 사이트맵을 페이지에 맞춰 **좁혔다**
+ *
+ * 반대(페이지를 넓히기)는 카테고리는 유효하다고 인정하면서 목록은
+ * `excludeCollections` 라 **비어 있는 화면**이 되거나, 그 prop 을 떼면 `/blog` 에
+ * 스트림 글이 새어 들어온다 — §2① 을 되돌리는 셈이라 택하지 않았다. 페이지가
+ * 실제로 서빙하는 집합이 이 라우트의 진실이고, 사이트맵은 거기에 따른다.
+ *
+ * ## "미소속" 판정은 서버가 한다
+ *
+ * `exclude_collections=true`(공개 posts API)는 **사이트가 선언한
+ * `content_collections`** 기준으로 미소속 글을 고른다 — 판정 정의가 DB 한 곳에
+ * 있다. 사이트맵 팩토리는 라우팅용 `collections` 를 모른 채 도는 경우가 많은데
+ * (레거시 모드 = `config.collections` 미전달), 이 서버 필터는 그 지식 없이도
+ * 페이지와 같은 집합을 준다. 클라이언트에서 각자 collections 목록을 조립해 거르면
+ * "어느 목록을 봤느냐" 에 따라 또 갈린다 — 그게 이 결함의 원인이었다.
+ *
+ * collection 모드 스트림 아카이브(`{basePath}/categories/{slug}`)의 모집단은
+ * 대칭적으로 `collectCollectionCategories`(포지티브 스코프: 그 스트림에 귀속된 글
+ * ∩ 스트림의 주제 allowlist) 하나다 — 사이트맵과 스트림 아카이브 페이지가 역시
+ * 같은 함수를 쓴다.
+ */
+
+/** 모집단 조회에 필요한 최소 설정 — `RootTaleSiteConfig` 가 구조적으로 만족한다. */
+interface ArchiveCategoriesConfig {
+    /** `rtlk_cust_*` — 블로그 조회와 같은 키. 서버에서만. */
+    apiKey: string;
+    /** API base 오버라이드. 기본 `https://api.roottale.com`. */
+    apiBase?: string;
+}
+interface ArchiveCategoriesOptions {
+    /** Next fetch 재검증 주기(초). 미지정 = cms-client 기본. */
+    revalidate?: number;
+}
+/**
+ * 레거시 `/blog` 계열 아카이브의 **모집단** — 어느 스트림에도 안 속한 발행 글.
+ *
+ * 한도는 `ARCHIVE_POST_COUNT_LIMIT`. 소비처마다 한도가 갈리면 같은 카테고리를 두고
+ * 사이트맵은 "글 있음", 페이지는 "0건 → 404" 가 된다(그래서 상수를 공유한다).
+ * 실패는 **throw** 한다 — 사이트맵은 always-200 이라 호출부에서 삼키고, 페이지는
+ * API 장애를 404 로 둔갑시키면 안 되므로 그대로 올린다(에러 정책이 서로 다르므로
+ * 여기서 임의로 fail-soft 하지 않는다).
+ */
+declare function fetchBlogArchivePosts(config: ArchiveCategoriesConfig, options?: ArchiveCategoriesOptions): Promise<CmsPostContent[]>;
+/**
+ * 레거시 `/blog` 계열 아카이브 라우트가 인정하는 카테고리 + 글 수.
+ *
+ * 사이트맵의 `/blog/categories/{slug}` 필터와 아카이브 페이지의 slug 유효성·
+ * `postCount` 가 **이 함수 하나**에서 나온다.
+ *
+ * ## 우선순위 — 서버 집계 → (실패 시) 최근 글 배치 파생
+ *
+ * 1순위는 서버측 집계 API 다. 발행 글 수와 무관하게 **모든** 분류의 정확한 글 수를
+ * 주므로, 최근 `ARCHIVE_POST_COUNT_LIMIT` 건 밖에만 글이 있는 분류가 페이지(404)·
+ * 사이트맵에서 함께 사라지던 한계가 없어진다.
+ *
+ * 서버 집계를 못 받으면(구버전 API·일시 장애) **옛 배치 파생으로 fail-soft** 한다 —
+ * 새 API 가 없다는 이유로 아카이브를 통째로 죽이지 않는다. 이때의 동작은 이 변경
+ * 이전과 정확히 같다(한도 안 분류만 인정). 배치 조회까지 실패하면 그때는 throw 가
+ * 그대로 올라간다(`fetchBlogArchivePosts` 주석 — API 장애를 404 로 둔갑시키지 않음).
+ *
+ * 두 경로 모두 이 함수 **하나**를 통과하므로, 사이트맵과 아카이브 페이지는 어느
+ * 경로가 쓰이든 같은 값을 본다(그 계약이 이 모듈의 존재 이유다).
+ */
+declare function fetchBlogArchiveCategories(config: ArchiveCategoriesConfig, options?: ArchiveCategoriesOptions): Promise<BlogCategoryWithCount[]>;
+
 /**
  * `@roottale/cms-renderer-next/routes` — Next.js App Router 통합 라우트 팩토리.
  *
@@ -594,4 +950,4 @@ interface FleetInfoRouteConfig {
  */
 declare function createFleetInfoRoute(config?: FleetInfoRouteConfig): () => Promise<Response>;
 
-export { type BuildPostMetadataOptions, type CollectionsInput, type FleetInfoRouteConfig, type ImageResponseLike, type LlmsTxtLink, type LlmsTxtRouteConfig, type LlmsTxtSection, OG_IMAGE_CONTENT_TYPE, OG_IMAGE_SIZE, type OgImageRouteConfig, type PostLocaleOptions, type PostMetadata, type PostMetadataInput, type PostSeoOverrides, type RedirectMiddlewareConfig, type RevalidateRouteConfig, type RootTaleSiteConfig, type SitemapEntry, type SitemapIndexOptions, type SitemapSectionId, buildHreflangLanguages, buildPostMetadata, createFeedRoute, createFleetInfoRoute, createLlmsTxtRoute, createPostOgImage, createRedirectMiddleware, createRevalidateRoute, createSitemap, createSitemapIndex, matchRedirect, normalizeRedirectPath, postRedirectPath, resolveCollections, resolveCollectionsResult, safeFetchPosts, trimSlash };
+export { ARCHIVE_POST_COUNT_LIMIT, type AlwaysNoindexArchiveKind, type ArchiveCategoriesConfig, type ArchiveCategoriesOptions, type ArchiveIndexDecision, type ArchiveIndexInput, type ArchiveKind, type ArchiveMetadata, type ArchiveMetadataFields, type ArchiveMetadataInput, type ArchivePromotion, type BuildArchiveMetadataOptions, type BuildPostMetadataOptions, type CollectionsInput, type FleetInfoRouteConfig, type ImageResponseLike, type LlmsTxtLink, type LlmsTxtRouteConfig, type LlmsTxtSection, OG_IMAGE_CONTENT_TYPE, OG_IMAGE_SIZE, type OgImageRouteConfig, type PostLocaleOptions, type PostMetadata, type PostMetadataInput, type PostSeoOverrides, type PromotableArchiveKind, type RedirectMiddlewareConfig, type RevalidateRouteConfig, type RobotsMeta, type RootTaleSiteConfig, type SitemapEntry, type SitemapIndexOptions, type SitemapSectionId, buildArchiveMetadata, buildHreflangLanguages, buildPostMetadata, createFeedRoute, createFleetInfoRoute, createLlmsTxtRoute, createPostOgImage, createRedirectMiddleware, createRevalidateRoute, createSitemap, createSitemapIndex, decideArchiveIndex, fetchBlogArchiveCategories, fetchBlogArchivePosts, matchRedirect, normalizeRedirectPath, postRedirectPath, resolveAuthorPromotion, resolveCategoryPromotion, resolveCollections, resolveCollectionsResult, resolveRobotsMeta, safeFetchPosts, trimSlash };