@zalkera/client 0.10.0 → 0.12.0

package/README.md

@@ -59,6 +59,19 @@ await zalkera.submitInquiry({name, email, subject, message}, {clientIp});
 - 설치 후 경로: `node_modules/@zalkera/client/llms.txt`.
 - 사용법: 이 파일을 AI 컨텍스트로 주고 "상품·장바구니·결제 페이지를 만들어줘".
 
+## AEO 보장표 (`contracts/aeo-surface-guarantees.json`)
+
+- `llms.txt` §5.1 이 말하는 산출물 규범의 **기계 판독본**. 설치 후 경로:
+  `node_modules/@zalkera/client/contracts/aeo-surface-guarantees.json`
+  패키지 하위 경로로도 열린다 — `require("@zalkera/client/contracts/aeo-surface-guarantees.json")`,
+  ESM 은 `import … with { type: "json" }`(실측 확인).
+- 이 표를 읽어 **개시된 사이트를 크롤해** 판정하는 **검사기도 이 패키지가 배송한다** —
+  `npx zalkera-aeo-check <사이트URL> --category BOOKING`(bin `zalkera-aeo-check`).
+  소스가 아니라 산출물을 재므로 스택·디자인을 가리지 않는다.
+  보장 주장이 없는 사이트는 `--category` 대신 `--site-wide-only`(robots·sitemap·JSON-LD 절대 URL 만).
+  스토어프론트 템플릿의 `npm run check:aeo` 는 이 bin 을 부르는 wrapper 다.
+- 정본은 잘커라 백엔드에 있고 여기 실린 것은 그 **발행 산출물**이다(발행 전 기계 대조).
+
 ## API 스펙 (메서드)
 
 ### 콘텐츠·공개(무인증)

package/bin/check-aeo-surfaces.mjs

@@ -0,0 +1,706 @@
+#!/usr/bin/env node
+/**
+ * AEO 보장 표면 검사기 (memo119 §1.3 · T5).
+ *
+ * **개시된 사이트를 크롤해 보장 그래프가 실제로 나오는지 잰다.** 소스를 읽지 않는 것이 요점이다
+ * (오너 전제 C): "이 섹션을 써라"는 디자인 자유를 깎지만 "개시된 페이지에서 이 그래프가 나오는가"는
+ * 아무것도 깎지 않는다. 그래서 이 검사기는 어떤 스택으로 짰든·어떤 섹션을 썼든 묻지 않고, 나온 HTML 만 본다.
+ *
+ * 잣대는 백엔드 정본 `doc/contracts/aeo-surface-guarantees.json` 이고 이 파일은 그 정본의 **집행자**다.
+ * 규범을 여기서 새로 만들지 않는다 — 표에 없는 것은 검사하지 않고, 표에 있는 것은 봐주지 않는다.
+ *
+ * ── 이 파일이 왜 client 패키지에 사는가(memo123 §6.1) ────────────────────────
+ * 원래 이 검사기는 `storefront-template/scripts/` 에 살았다. 그런데 이제 **사람이 CLI 로 치는 것 말고도**
+ * 두 자리에서 돌아야 한다: ⑴ 고객 zip(원래 자리) ⑵ serving-orchestrator 가 발행 직후 자동으로 재는 자리.
+ * ⑵의 실행체는 "외부 의존 0 단일 `server.mjs`"라는 속성을 지켜야 해서 검사기를 자기 안에 넣을 수 없고,
+ * 대신 **툴킷 디렉터리에 `npm i @zalkera/client@<pin>` 해서 그 bin 을 child 로 spawn** 한다.
+ * 사본을 하나 더 두면 두 검사기가 조용히 갈라지므로(`lib/site-crawl.mjs` 의 KDoc 과 같은 논거) 정본을
+ * 여기로 옮기고 template 의 `scripts/check-aeo-surfaces.mjs` 는 이 bin 을 부르는 **얇은 wrapper** 다.
+ *
+ * ── 잣대를 어디서 찾는가(memo122 §1.3-2) ────────────────────────────────────
+ * 이 검사기는 고객 zip 에 실려 나간다. 그런데 **잣대는 실려 나가지 않아서** 고객 기계에서는 기본 경로
+ * (형제 `../backend`)가 없어 exit 2 로 죽어 있었다(2026-07-29 실측). 그래서 해석을 3단으로 둔다:
+ *
+ *   ① `--guarantees <경로>`                       — 명시가 언제나 이긴다
+ *   ② `@zalkera/client/contracts/…`(npm 운반본)   — **고객의 기본 경로**. zip 에 이 의존이 이미 있어
+ *                                                   `npm i` 만 하면 잣대가 따라온다. 이 파일이 그 패키지
+ *                                                   안에 살므로 **자기 패키지의 운반본**이 1순위 후보다
+ *   ③ 형제 `../backend/doc/contracts/…`(정본)     — 우리 개발 체크아웃 관례 폴백
+ *
+ * 정본은 여전히 백엔드 하나이고 ②는 그 **발행 산출물**이다(client 발행 전 `sync-aeo-guarantees.mjs` 가
+ * 바이트 동일을 강제한다). ②로 재는 자리에 ③도 함께 있으면 둘을 비교해 **갈라짐을 경고**한다 — 운반본이
+ * 낡았는데 그걸로 잰 판정을 정본 판정처럼 읽는 것이 이 3단 구조의 유일한 새 위험이라서다.
+ * ③의 후보 자리는 **이 파일 기준과 실행 위치(cwd) 기준 둘 다** 본다: 이 파일이 패키지 안으로 들어오면서
+ * "파일 기준 형제"는 `node_modules/backend` 라는 없는 경로가 됐고, 그것만 보면 개발 체크아웃에서
+ * 드리프트 경고가 조용히 꺼진다(옮기면서 잃을 뻔한 축이라 여기 적어 둔다).
+ *
+ * ── 사용 ────────────────────────────────────────────────────────────────────
+ *   npx zalkera-aeo-check <사이트URL> --category BOOKING [--category BLOG] \
+ *        [--code beauty-nail --version 1.0.0] \
+ *        [--guarantees ../backend/doc/contracts/aeo-surface-guarantees.json] \
+ *        [--out out/aeo-snapshot.json] [--max-pages 60] [--route /추가경로]…
+ *   (스토어프론트 체크아웃·고객 zip 안에서는 `npm run check:aeo -- …` 가 같은 bin 을 부른다)
+ *
+ *   npx zalkera-aeo-check <사이트URL> --site-wide-only
+ *        **보장 주장이 없는 사이트**를 재는 모드(memo123 §6.3 B-1). `--category` 를 요구하지 않고
+ *        siteWide 버킷(robots·sitemap·JSON-LD 절대 URL)만 잰다. 카테고리 required 는 아예 판정하지
+ *        않는다 — 어휘 준수를 주장한 적 없는 사이트에 그 잣대를 들이대는 것은 오너 전제 A(디자인 자유)를
+ *        어기는 일이다. 발행 직후 자동 검사(orchestrator)가 전 사이트에 쓰는 모드가 이것이다.
+ *
+ *   npx zalkera-aeo-check --print-guarantees
+ *        잣대 해석만 해 보고 끝낸다(사이트 크롤 없음·네트워크 불요). 어떤 출처의 어느 rev 로 재는지와
+ *        고를 수 있는 `--category` 목록을 찍는다. `verify-zip.mjs` 가 zip 안에서 이걸 돌려 "검사기가
+ *        살아서 뜨는가"를 기계로 확인한다 — 조용히 죽는 상태가 다시 생기면 zip 게이트가 잡는다.
+ *
+ * 종료코드: 0=required 전부 통과 · 1=보장 미충족(red) · 2=실행 불가(인자·네트워크·표 부재)
+ *
+ * ── red 는 결함 보고이지 실패가 아니다 ──────────────────────────────────────
+ * 이 검사기를 처음 돌리면 **우리 팩부터 red 가 난다**(§0-6 실측: CMS JsonLd 0·상품 목록 라우트 부재·
+ * ItemList 0·openingHours 저장 자리 없음). 그건 검사기가 잘못 만들어진 신호가 아니라 **본보기 정합
+ * 작업(T6)의 지시서**다. 통과시키려고 표를 낮추면 보장이 거짓이 되고, 그 순간 이 파일은 쓸모가 없어진다.
+ *
+ * ── 무엇을 실패로 세지 않는가 ────────────────────────────────────────────────
+ *  · `planned` — 표가 목표로 적어 뒀지만 아직 우리도 못 내는 표면. PLANNED_MISSING 으로 보고만 한다.
+ *  · `conditional` — 섹션이 있을 때만 성립하는 표면(FAQPage). 크롤한 HTML 만으로는 "섹션을 안 썼다"와
+ *    "썼는데 그래프가 없다"를 구분할 수 없으므로, 안 보이면 SKIPPED 다. 못 세는 것을 센 척하지 않는다.
+ *  · `TESTIMONIALS` 의 Review·별점 — 이건 **의도적 부정 보장**이라 없는 것이 정답이고, 오히려 나오면
+ *    실패다(self-serving reviews 정책 위반). 누락으로 잡으면 검사기가 정책을 거꾸로 아는 것이다.
+ */
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from "node:fs";
+import {createRequire} from "node:module";
+import {dirname, join, resolve} from "node:path";
+import {fileURLToPath} from "node:url";
+import {FUNCTIONAL_SEGMENTS, crawlPages, makeClassifier} from "../lib/site-crawl.mjs";
+
+/**
+ * 판정 형식이 바뀌면 올린다 — 스냅샷에 박혀서 "어느 잣대로 잰 판정인가"가 사후에도 남는다.
+ *
+ * 2 = `--site-wide-only` 모드와 스냅샷의 `mode` 필드 추가(memo123 §6.3). 기존 카테고리 판정의 잣대는
+ * 하나도 안 바뀌었지만, 스냅샷 형식에 필드가 늘었고 그 필드를 읽는 소비자(promote 게이트·백엔드 ingest)가
+ * "구판 스냅샷인가"를 이 수로 가른다.
+ */
+const CHECKER_VERSION = 2;
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// ── 인자 ─────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback = undefined) => {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : fallback;
+};
+const flagAll = (name) => {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === `--${name}` && argv[i + 1] && !argv[i + 1].startsWith("--")) out.push(argv[i + 1]);
+    }
+    return out;
+};
+const die = (msg) => {
+    console.error(msg);
+    process.exit(2);
+};
+
+const siteUrl = argv.find((a) => !a.startsWith("--") && /^https?:\/\//.test(a));
+const categories = flagAll("category");
+const printOnly = argv.includes("--print-guarantees");
+/**
+ * 무주장 모드(memo123 §6.3 B-1). **카테고리 판정을 아예 하지 않는다** — 끄는 것이 아니라 안 하는 것이다.
+ * 보장 어휘를 주장한 적 없는 사이트에 그 잣대를 대면, 그 사이트가 어떤 스택으로 짰든 red 가 쏟아지고
+ * 그 red 는 사실이 아니라 **잣대를 잘못 고른 결과**다(오너 전제 A). 그래서 카테고리 축은 판정에서 빠지고
+ * 사이트 축(robots·sitemap·절대 URL)만 남는다 — 그 셋은 어떤 디자인 선택과도 무관한 기계 가독 최소치다.
+ */
+const siteWideOnly = argv.includes("--site-wide-only");
+if (!printOnly && !siteUrl) {
+    die("사용: zalkera-aeo-check <사이트URL> --category <코드> [--category …] [--code …] [--version …] [--out …]\n      무주장 사이트: zalkera-aeo-check <사이트URL> --site-wide-only\n      (잣대 해석만 확인: zalkera-aeo-check --print-guarantees)");
+}
+if (!printOnly && siteWideOnly && categories.length > 0) {
+    // 둘 다 주면 어느 쪽을 원한 것인지 알 수 없다. 조용히 한쪽을 이기게 하면 "쟀다고 생각한 것"과
+    // "잰 것"이 갈라지고, 그 갈라짐은 스냅샷을 봐야만 보인다.
+    die("--site-wide-only 와 --category 는 같이 못 준다 — 카테고리 판정을 하든지, 사이트 축만 재든지 하나다.");
+}
+if (!printOnly && !siteWideOnly && categories.length === 0) {
+    die("--category 가 없다. 보장 주장이 있는 팩이면 그 코드를, 무주장 사이트면 --site-wide-only 를 주십시오.");
+}
+
+// ── 잣대 해석 — 명시 > @zalkera/client 운반본 > 형제 백엔드 정본(파일 머리말 참조) ──
+
+const CARRIED_SPECIFIER = "@zalkera/client/contracts/aeo-surface-guarantees.json";
+/** 이 파일이 사는 패키지 자신의 운반본. bin 으로 돌 때 **가장 확실한 자리**다(해석을 거칠 필요가 없다). */
+const OWN_CARRIED = join(ROOT, "contracts", "aeo-surface-guarantees.json");
+/**
+ * 형제 백엔드 정본 후보. **두 기준점을 다 본다** — 이 파일이 패키지 안으로 들어오면서 파일 기준 형제는
+ * `node_modules/backend` 라는 없는 경로가 됐고, 실행 위치(cwd) 기준이 개발 체크아웃의 실제 형상이다.
+ */
+const SIBLING_CANDIDATES = [...new Set([join(ROOT, ".."), process.cwd()])].map((base) =>
+    join(base, "..", "backend", "doc/contracts/aeo-surface-guarantees.json"),
+);
+const siblingCanonical = () => SIBLING_CANDIDATES.find((p) => existsSync(p)) ?? null;
+const requireFrom = createRequire(import.meta.url);
+
+/**
+ * 설치된 `@zalkera/client` 안의 운반본 경로. **패키지 해석에 맡긴다** — 경로를 손으로 짜면
+ * (`node_modules/@zalkera/client/…`) 워크스페이스 호이스팅·pnpm 링크에서 조용히 빗나간다.
+ * 검사기 자리 기준으로 먼저 찾고, 그래도 없으면 실행 위치 기준으로 한 번 더 본다
+ * (검사기만 다른 데로 복사해 쓰는 경우 — 실제로 그렇게 돌려 본 적이 있다).
+ */
+function resolveCarried() {
+    for (const from of [ROOT, process.cwd()]) {
+        try {
+            return requireFrom.resolve(CARRIED_SPECIFIER, {paths: [from]});
+        } catch {
+            /* 다음 후보 */
+        }
+    }
+    return null;
+}
+
+function resolveGuarantees() {
+    const explicit = flag("guarantees");
+    if (explicit) return {path: resolve(explicit), source: "--guarantees 인자"};
+    if (existsSync(OWN_CARRIED)) return {path: OWN_CARRIED, source: "@zalkera/client 운반본(자기 패키지)"};
+    const carried = resolveCarried();
+    if (carried) return {path: carried, source: `@zalkera/client 운반본(${CARRIED_SPECIFIER})`};
+    const sibling = siblingCanonical();
+    if (sibling) return {path: sibling, source: "형제 백엔드 정본(개발 체크아웃)"};
+    return {path: null, source: null};
+}
+
+/** 패키지 자체는 설치돼 있는가 — "안 깔림"과 "깔렸는데 운반본이 없는 구 버전"은 고칠 방법이 다르다. */
+function clientInstalled() {
+    for (const from of [ROOT, process.cwd()]) {
+        try {
+            requireFrom.resolve("@zalkera/client", {paths: [from]});
+            return true;
+        } catch {
+            /* 다음 후보 */
+        }
+    }
+    return false;
+}
+
+const resolved = resolveGuarantees();
+if (!resolved.path) {
+    die(
+        "보장표(잣대)를 못 찾았다 — 아무 판정도 하지 않는다. 없는 잣대로 통과시키는 것보다 안 재는 편이 정직하다.\n" +
+            "   찾아본 곳:\n" +
+            `   ① --guarantees 인자 — 안 줬다\n` +
+            `   ② ${CARRIED_SPECIFIER} — ${
+                clientInstalled()
+                    ? "@zalkera/client 는 설치돼 있는데 그 안에 보장표가 없다(운반본을 싣지 않는 구 버전 — `npm i @zalkera/client@latest` 로 올리십시오)."
+                    : "@zalkera/client 가 설치돼 있지 않다. 이 디렉터리에서 `npm install` 을 먼저 돌리십시오."
+            }\n` +
+            `   ③ ${SIBLING_CANDIDATES.join(" · ")} — 없다(우리 개발 체크아웃 관례라 고객 기계에는 원래 없다)`,
+    );
+}
+const specPath = resolved.path;
+const themeCode = flag("code", null);
+const themeVersion = flag("version", null);
+const outPath = flag("out", "");
+const maxPages = Number(flag("max-pages", "60"));
+const extraRoutes = flagAll("route");
+
+let specText;
+let spec;
+try {
+    specText = readFileSync(specPath, "utf8");
+    spec = JSON.parse(specText);
+} catch (e) {
+    die(`보장표를 못 읽었다: ${specPath}\n   ${e.message}\n   --guarantees 로 다른 경로를 주십시오.`);
+}
+
+/**
+ * 운반본으로 재는데 정본도 곁에 있으면 대조한다. 갈라져 있으면 **판정 자체가 낡은 잣대의 판정**이므로
+ * 조용히 넘기지 않는다 — 막지는 않는다(정본이 있는 자리는 우리 개발 체크아웃뿐이고, 그때 필요한 것은
+ * 차단이 아니라 "client 발행이 밀렸다"는 신호다).
+ */
+let carriedDrift = null;
+const siblingForDrift = resolved.source?.startsWith("@zalkera/client") ? siblingCanonical() : null;
+if (siblingForDrift) {
+    try {
+        if (readFileSync(siblingForDrift, "utf8") !== specText) {
+            carriedDrift = `운반본이 형제 백엔드 정본과 다르다 — client 발행이 밀렸을 수 있다(${siblingForDrift} 로 재려면 --guarantees 로 지정).`;
+        }
+    } catch {
+        /* 정본을 못 읽으면 대조를 포기한다 — 이 축은 경고이지 게이트가 아니다 */
+    }
+}
+
+const byCategory = new Map((spec.categories ?? []).map((c) => [c.category, c]));
+
+if (printOnly) {
+    console.log(`· 잣대 출처 ${resolved.source}`);
+    console.log(`· 경로 ${specPath}`);
+    console.log(`· 보장표 rev ${spec.contractRev} · 카테고리 ${[...byCategory.keys()].join(", ")}`);
+    if (carriedDrift) console.warn(`⚠️  ${carriedDrift}`);
+    console.log(`· 사이트 축(무주장) 검사 항목 ${(spec.siteWide?.requirements ?? []).map((r) => r.id).join(", ")} — \`--site-wide-only\``);
+    console.log("· 잣대 해석 성공 — 이제 사이트 URL 과 --category(또는 --site-wide-only)를 주면 실제로 잽니다.");
+    process.exit(0);
+}
+
+for (const c of categories) {
+    if (!byCategory.has(c)) {
+        // 표에 없는 이름은 **순수 라벨**이다(예: "미니멀"). 보장 주장이 없으므로 잴 것도 없고,
+        // 억지로 통과시킨 스냅샷을 만들면 promote 게이트가 의미를 잃는다.
+        die(`'${c}' 는 보장표에 없는 이름이라 검사 대상이 아니다(순수 라벨). 등재된 카테고리: ${[...byCategory.keys()].join(", ")}`);
+    }
+}
+
+const origin = new URL(siteUrl).origin;
+const classify = makeClassifier({origin, skipRoutes: new Set()}); // 검사기는 아무것도 공개하지 않는다 — /policies 도 훑는다
+
+// ── JSON-LD 추출 ─────────────────────────────────────────────────────────────
+
+const LD_RE = /<script[^>]+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+
+/** 한 노드를 그 자신 + 중첩 노드 전부로 편다. `@graph`·배열·중첩 객체를 같은 방식으로 훑는다. */
+function flattenNodes(value, out = []) {
+    if (Array.isArray(value)) {
+        for (const v of value) flattenNodes(v, out);
+        return out;
+    }
+    if (value && typeof value === "object") {
+        if (value["@type"] !== undefined) out.push(value);
+        for (const v of Object.values(value)) flattenNodes(v, out);
+    }
+    return out;
+}
+
+const typesOf = (node) => {
+    const t = node["@type"];
+    return Array.isArray(t) ? t.map(String) : t == null ? [] : [String(t)];
+};
+
+/**
+ * 페이지에서 JSON-LD 를 꺼낸다. 파싱 실패는 **버리지 않고 기록**한다 — 깨진 JSON-LD 는 없는 것보다
+ * 나쁘고(크롤러가 페이지 전체의 구조화 데이터를 버린다), 조용히 넘기면 그 사실이 안 보인다.
+ * `JsonLd.tsx` 가 `<` 를 `<` 로 이스케이프하므로 `</script>` 조기 종료는 나지 않는다.
+ */
+function extractJsonLd(html) {
+    const roots = [];
+    const nodes = [];
+    const malformed = [];
+    LD_RE.lastIndex = 0;
+    let m;
+    while ((m = LD_RE.exec(html)) !== null) {
+        try {
+            const parsed = JSON.parse(m[1]);
+            for (const r of Array.isArray(parsed) ? parsed : [parsed]) roots.push(r);
+            flattenNodes(parsed, nodes);
+        } catch (e) {
+            malformed.push(e.message);
+        }
+    }
+    return {roots, nodes, malformed};
+}
+
+/** 태그를 걷어낸 순수 텍스트. */
+function textOf(html) {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&[a-z#0-9]+;/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+
+/** 지정 태그의 요소를 **내용째** 걷어낸다. 상대하는 마크업이 우리가 낸 것이라(임의 웹이 아니다) 중첩 동명 태그는 없다. */
+function stripElements(html, ...tags) {
+    return tags.reduce((acc, tag) => acc.replace(new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?<\\/${tag}>`, "gi"), " "), html);
+}
+
+/**
+ * SSR 판정 — **JS 실행 없이 그 페이지의 주제와 본문이 응답에 실려 있는가.**
+ *
+ * 계약이 `cms-page-ssr`·`post-list-ssr` 의 why 에 적은 요구가 그대로 잣대다: "본문이 JS 실행 없이 응답
+ * 본문에 실려야 한다." 그래서 **제목만으로는 통과가 아니다** — 제목 검증으로 줄이면 h1 만 서버에서 그리고
+ * 본문은 클라이언트가 fetch 하는 팩이 보장 배지를 받는다(이 검사기는 티어 B/C 서드파티 팩에 동등 배지를
+ * 주는 유일한 잣대라 그 순간 배지가 거짓이 된다).
+ *
+ * 판정 잣대를 "글자 수 N자 이상"으로 두려다 실측에서 **거짓 red** 를 냈다: 상품 상세가 104자, 글이
+ * 0건인 블로그 목록이 14자였는데 둘 다 서버가 정상 렌더한 페이지였다. 짧은 것은 렌더 실패가 아니라
+ * **콘텐츠가 짧은 것**이고, 그 둘을 길이로는 못 가른다. 그래서 길이가 아니라 **자리**로 가른다:
+ *
+ *  ① `<h1>` 에 글자가 있는가 — 그 페이지가 무엇에 관한 것인지 서버가 이미 말했는가.
+ *     클라이언트에서만 그리는 셸은 여기가 비어 있다(레이아웃의 헤더·푸터에는 h1 이 없다).
+ *  ② 본문 범위에서 **h1 자신을 뺀 잔여**에 글자가 하나라도 있는가. h1 을 빼지 않으면 제목 글자가
+ *     본문으로 세어져 ②가 ①의 되풀이가 된다(실측: `<main><h1>젤 네일</h1><div id="app"/></main>` 통과).
+ *     빈 상태 문구("게시글이 없습니다")는 h1 밖에 있으므로 여전히 통과다 — 그건 데이터가 없는 것이지
+ *     렌더가 없는 것이 아니다. 상품 상세도 h1 밖에 설명·가격이 있어 통과한다.
+ *
+ * 본문 범위는 `<main>` 안쪽이고, `<main>` 이 없으면 **head·header/nav/footer 를 걷어낸 나머지**다.
+ * 문서 전체를 폴백으로 쓰면 `<title>` 과 헤더 내비 글자만으로 셸이 통과한다(실측 확인).
+ *
+ * 그래프를 요구하는 라우트에는 더 강한 증거가 이미 있다 — **JSON-LD 가 원본 응답에 실려 왔다는 사실**
+ * 자체가 서버 렌더의 증명이다. 그래서 이 판정은 그래프가 없는 표면(목록·고정 페이지)에서 주로 일한다.
+ */
+function judgeSsr(html) {
+    const h1 = /<h1[^>]*>([\s\S]*?)<\/h1>/i.exec(html);
+    const h1Text = h1 ? textOf(h1[1]) : "";
+    if (!h1Text) return {ok: false, why: "서버 응답에 글자 있는 <h1> 이 없다(클라이언트에서만 그리는 셸)"};
+    const main = /<main[^>]*>([\s\S]*?)<\/main>/i.exec(html);
+    const scope = main ? main[1] : stripElements(html, "head", "header", "nav", "footer");
+    const bodyText = textOf(stripElements(scope, "h1"));
+    if (!bodyText) {
+        return {
+            ok: false,
+            why: main
+                ? "<main> 에 제목뿐이고 본문이 없다 — 본문을 클라이언트에서 그리는 부분 CSR 이다"
+                : "<main> 이 없고 제목 밖 본문도 응답에 없다 — 클라이언트에서만 그리는 셸이다",
+        };
+    }
+    return {ok: true};
+}
+
+// ── 라우트 해석 ──────────────────────────────────────────────────────────────
+
+const routeDefs = Object.fromEntries(Object.entries(spec.routes ?? {}).filter(([k]) => !k.startsWith("$")));
+
+/**
+ * 예약 세그먼트 — `/{slug}` 인스턴스 후보에서 뺀다. **표에서 유도한다**(하드코딩 2벌 금지):
+ * 다른 라우트들의 리터럴 선두 세그먼트 + 기능 세그먼트 + 식별정보 라우트.
+ */
+const reservedFirstSegments = new Set([...FUNCTIONAL_SEGMENTS, "policies", "contact"]);
+for (const def of Object.values(routeDefs)) {
+    const p = def.path ?? def.pattern ?? "";
+    const first = p.split("/").filter(Boolean)[0];
+    if (first && !first.startsWith("{")) reservedFirstSegments.add(first);
+}
+
+function instanceMatcher(pattern) {
+    const segs = pattern.split("/").filter(Boolean);
+    return (path) => {
+        const got = path.split("/").filter(Boolean);
+        if (got.length !== segs.length) return false;
+        for (let i = 0; i < segs.length; i++) {
+            if (segs[i].startsWith("{")) {
+                if (i === 0 && reservedFirstSegments.has(got[i])) return false;
+            } else if (segs[i] !== got[i]) return false;
+        }
+        return true;
+    };
+}
+
+// ── 크롤 ─────────────────────────────────────────────────────────────────────
+
+/** 표가 요구하는 리터럴 라우트는 링크가 없어도 직접 두드린다 — **라우트 부재가 곧 보장 부재**라서다. */
+const literalRoutes = Object.values(routeDefs)
+    .filter((d) => d.kind === "LITERAL")
+    .map((d) => d.path);
+
+/** 기계용 파일은 크롤러가 페이지로 안 받는다(blocked) — 따로 두드린다. */
+async function fetchText(path) {
+    try {
+        const res = await fetch(origin + path, {headers: {"user-agent": "zalkera-aeo-check"}});
+        return res.ok ? await res.text() : null;
+    } catch {
+        return null;
+    }
+}
+
+console.log(`· 대상 ${siteUrl} · ${siteWideOnly ? "무주장(사이트 축만)" : `카테고리 ${categories.join(", ")}`} · 보장표 rev ${spec.contractRev}`);
+console.log(`· 잣대 출처 ${resolved.source} — ${specPath}`);
+if (carriedDrift) console.warn(`⚠️  ${carriedDrift}`);
+
+const robotsTxt = await fetchText("/robots.txt");
+const sitemapXml = await fetchText("/sitemap.xml");
+const sitemapLocs = new Set(
+    [...(sitemapXml ?? "").matchAll(/<loc>\s*([^<]+?)\s*<\/loc>/gi)].map((m) => {
+        try {
+            return new URL(m[1]).pathname.replace(/\/+$/, "") || "/";
+        } catch {
+            return m[1];
+        }
+    }),
+);
+
+/**
+ * **sitemap 을 크롤 시드로 쓴다.** 링크 추적만으로는 목록 라우트가 없는 사이트에서 상품 상세를 영영 못
+ * 만난다(실측: 상품 5행이 있는데 /products 가 없어 상세가 0건으로 잡혔다) — 그건 목록 부재의 결과이지
+ * 상세 부재가 아닌데 검사기가 둘을 섞어 보고하면 T6 지시서가 흐려진다. sitemap 은 사이트 자신이 신고한
+ * 공개 라우트 목록이라 이 용도의 정당한 출처다. 없으면(sitemap 부재) 링크 추적만으로 돈다.
+ */
+const sitemapSeed = [...sitemapLocs].filter((p) => p.startsWith("/"));
+
+const crawled = await crawlPages({
+    origin,
+    entryPath: new URL(siteUrl).pathname.replace(/\/+$/, "") || "/",
+    extraRoutes: [...literalRoutes, ...sitemapSeed, ...extraRoutes],
+    maxPages,
+    classify,
+    userAgent: "zalkera-aeo-check",
+    onPage: (p) => console.log(`  · 크롤 ${p}`),
+});
+
+if (crawled.pages.size === 0) {
+    die(`크롤한 페이지가 0건이다 — 사이트가 응답하지 않는다.\n${crawled.fetchFailures.map((f) => `   · ${f}`).join("\n")}`);
+}
+
+/** 라우트 → {status, html, ld}. 못 받은 라우트는 여기 없다(= 부재). */
+const seen = new Map();
+for (const [path, html] of crawled.pages) seen.set(path, {html, ld: extractJsonLd(html)});
+
+// ── 판정 ─────────────────────────────────────────────────────────────────────
+
+/** 라우트 이름 → 검사 대상 페이지. LITERAL 은 그 경로, INSTANCE 는 크롤에서 찾은 실물 한 건. */
+function resolveRoute(name) {
+    if (name === "any") return {kind: "ANY"};
+    const def = routeDefs[name];
+    if (!def) return {kind: "UNKNOWN"};
+    if (def.kind === "LITERAL") {
+        const page = seen.get(def.path);
+        return page ? {kind: "PAGE", path: def.path, page} : {kind: "MISSING", path: def.path};
+    }
+    const match = instanceMatcher(def.pattern);
+    for (const [path, page] of seen) if (match(path)) return {kind: "PAGE", path, page};
+    return {kind: "MISSING", path: def.pattern};
+}
+
+const pageHasType = (page, type) => page.ld.nodes.some((n) => typesOf(n).includes(type));
+const anyPageHasType = (type) => [...seen.values()].some((p) => pageHasType(p, type));
+
+/** `requiredChildren` — 그 타입 노드 **안에** 자식 타입이 있는가(Product 안의 Offer 처럼). */
+function nodeContainsType(node, type) {
+    return flattenNodes(node).some((n) => n !== node && typesOf(n).includes(type));
+}
+
+function judgeSurface(surface, bucket) {
+    const base = {id: surface.id, bucket, route: surface.route ?? null, jsonLd: surface.jsonLd ?? []};
+    const target = resolveRoute(surface.route ?? "any");
+
+    if (target.kind === "UNKNOWN") return {...base, status: "ERROR", detail: `모르는 라우트 참조 '${surface.route}'`};
+
+    // 라우트가 없다 = 표면이 없다. 스킵이 아니라 미충족이다.
+    if (target.kind === "MISSING") {
+        return {...base, status: "MISSING_ROUTE", detail: `라우트 부재 — ${target.path} 가 응답하지 않거나 실물이 0건이다`};
+    }
+
+    const types = surface.jsonLd ?? [];
+    const hasType = (t) => (target.kind === "ANY" ? anyPageHasType(t) : pageHasType(target.page, t));
+    const at = target.kind === "ANY" ? "(사이트 어디든)" : target.path;
+
+    // ① JSON-LD 타입 — 배열이면 그중 **하나라도** 있으면 통과(Organization|LocalBusiness|BeautySalon 처럼 좁힘 허용).
+    if (types.length > 0) {
+        const found = types.filter(hasType);
+        if (found.length === 0) {
+            return {...base, at, status: "MISSING_JSONLD", detail: `${at} 에 ${types.join("|")} 그래프가 없다`};
+        }
+        for (const child of surface.requiredChildren ?? []) {
+            const carriers =
+                target.kind === "ANY"
+                    ? [...seen.values()].flatMap((p) => p.ld.nodes)
+                    : target.page.ld.nodes;
+            const ok = carriers.some((n) => found.some((t) => typesOf(n).includes(t)) && nodeContainsType(n, child));
+            if (!ok) {
+                return {...base, at, status: "MISSING_CHILD", detail: `${at} 의 ${found[0]} 안에 ${child} 가 없다`};
+            }
+        }
+    }
+
+    // ①-b 그래프 **속성** 요구(openingHours 처럼 타입이 아니라 필드인 것).
+    if (surface.jsonLdProperty) {
+        const pool = target.kind === "ANY" ? [...seen.values()].flatMap((p) => p.ld.nodes) : target.page.ld.nodes;
+        if (!pool.some((n) => n[surface.jsonLdProperty] != null)) {
+            return {...base, at, status: "MISSING_PROPERTY", detail: `${at} 의 JSON-LD 에 ${surface.jsonLdProperty} 속성이 없다`};
+        }
+    }
+
+    // ② SSR — JS 실행 없이 본문이 실려 있는가.
+    if (surface.ssr && target.kind === "PAGE") {
+        const ssr = judgeSsr(target.page.html);
+        if (!ssr.ok) return {...base, at, status: "NOT_SSR", detail: `${at} — ${ssr.why}`};
+    }
+
+    // ③ 깨진 JSON-LD 는 없는 것보다 나쁘다.
+    if (target.kind === "PAGE" && target.page.ld.malformed.length > 0) {
+        return {...base, at, status: "MALFORMED_JSONLD", detail: `${at} 의 JSON-LD 파싱 실패 ${target.page.ld.malformed.length}건`};
+    }
+
+    return {...base, at, status: "PASS"};
+}
+
+/**
+ * siteWide 요건 — 라우트 축이 아니라 사이트 축이라 판정이 따로 산다.
+ *
+ * `requiredRoutePaths` 가 **null 이면 주장이 없는 것**(무주장 모드)이고, 빈 배열이면 주장은 있는데 그
+ * 라우트가 하나도 안 잡힌 것이다. 둘을 같게 다루면 `SITEMAP_COVERS` 가 "덮을 대상이 0건이라 통과"라는
+ * 공허한 PASS 를 찍는다 — 안 잰 것을 통과로 세지 않는 것이 이 검사기의 규율이다.
+ */
+function judgeSiteWide(req, requiredRoutePaths) {
+    const base = {id: req.id, bucket: "siteWide", check: req.check};
+    if (req.check === "SITEMAP_COVERS" && requiredRoutePaths === null) {
+        return {...base, status: "SKIPPED", detail: "보장 카테고리를 주장하지 않아 sitemap 이 덮어야 할 라우트가 정해지지 않는다"};
+    }
+    switch (req.check) {
+        case "ROBOTS_PRESENT":
+            return robotsTxt == null
+                ? {...base, status: "MISSING", detail: "/robots.txt 가 응답하지 않는다"}
+                : {...base, status: "PASS"};
+        case "SITEMAP_PRESENT":
+            return sitemapXml == null
+                ? {...base, status: "MISSING", detail: "/sitemap.xml 이 응답하지 않는다"}
+                : {...base, status: "PASS"};
+        case "SITEMAP_COVERS": {
+            if (sitemapXml == null) return {...base, status: "MISSING", detail: "sitemap 자체가 없다"};
+            const missing = requiredRoutePaths.filter((p) => !sitemapLocs.has(p));
+            return missing.length
+                ? {...base, status: "MISSING", detail: `sitemap 이 보장 라우트를 안 싣는다 — ${missing.join(", ")}`}
+                : {...base, status: "PASS"};
+        }
+        case "ABSOLUTE_URLS_IN_JSONLD": {
+            const bad = [];
+            for (const [path, page] of seen) {
+                for (const node of page.ld.nodes) {
+                    for (const key of ["url", "item", "@id"]) {
+                        const v = node[key];
+                        if (typeof v === "string" && v && !/^https?:\/\//i.test(v)) bad.push(`${path}: ${key}="${v}"`);
+                    }
+                }
+            }
+            return bad.length
+                ? {...base, status: "RELATIVE_URL", detail: `절대 URL 이 아니다 — ${bad.slice(0, 5).join(" · ")}`}
+                : {...base, status: "PASS"};
+        }
+        default:
+            return {...base, status: "ERROR", detail: `모르는 검사 종류 '${req.check}'`};
+    }
+}
+
+/** 부정 보장 — 나오면 실패다. 없는 것이 정답인 항목이라 '누락'으로 세면 안 된다. */
+function judgeNegative() {
+    const out = [];
+    for (const rule of spec.negative?.forbiddenTypes ?? []) {
+        const hits = [];
+        for (const [path, page] of seen) {
+            const pool = rule.scope === "ROOT_ONLY" ? page.ld.roots : page.ld.nodes;
+            for (const n of pool) {
+                if (n && typeof n === "object" && typesOf(n).includes(rule.type)) hits.push(path);
+            }
+        }
+        out.push(
+            hits.length
+                ? {id: `no-${rule.type}`, bucket: "negative", status: "FORBIDDEN_PRESENT", detail: `${rule.type} 가 나왔다 — ${[...new Set(hits)].join(", ")}`}
+                : {id: `no-${rule.type}`, bucket: "negative", status: "PASS"},
+        );
+    }
+    return out;
+}
+
+// ── 실행 ─────────────────────────────────────────────────────────────────────
+
+const FAIL_STATUSES = new Set(["MISSING_ROUTE", "MISSING_JSONLD", "MISSING_CHILD", "MISSING_PROPERTY", "NOT_SSR", "MALFORMED_JSONLD", "MISSING", "RELATIVE_URL", "FORBIDDEN_PRESENT", "ERROR"]);
+
+const results = [];
+
+if (siteWideOnly) {
+    /**
+     * 무주장 판정 — **사이트 축만**(memo123 §6.3). 카테고리 required·conditional·planned 는 물론
+     * `negative`(부정 보장)도 여기서는 안 잰다: 부정 보장은 "우리 어휘를 쓰는 팩이 자사 별점을 달지
+     * 않는다"는 우리 팩의 규율이고, 남의 사이트가 자기 후기 마크업을 어떻게 다는지는 우리가 판정할
+     * 자리가 아니다(전제 A). B-2 에서 주장 앵커가 생기면 그 사이트에는 잰다.
+     */
+    const surfaces = (spec.siteWide?.requirements ?? []).map((req) => judgeSiteWide(req, null));
+    const failed = surfaces.filter((s) => FAIL_STATUSES.has(s.status));
+    results.push({
+        category: null,
+        label: "사이트 축(무주장)",
+        shipState: null,
+        verdict: failed.length === 0 ? "PASS" : "FAIL",
+        surfaces,
+    });
+}
+
+for (const code of categories) {
+    const cat = byCategory.get(code);
+    const surfaces = [];
+
+    for (const s of cat.required ?? []) surfaces.push(judgeSurface(s, "required"));
+    for (const s of cat.conditional ?? []) {
+        const r = judgeSurface(s, "conditional");
+        // 조건부는 못 찾으면 SKIPPED — "섹션을 안 썼다"와 구별할 수 없다(§EVENT/faq-page why).
+        surfaces.push(r.status === "PASS" ? r : {...r, status: "SKIPPED", detail: `${r.detail ?? ""} (섹션 미사용일 수 있어 실패로 세지 않는다)`.trim()});
+    }
+    for (const s of cat.planned ?? []) {
+        const r = judgeSurface(s, "planned");
+        // planned 는 게이트가 아니라 T6 작업 지시서다.
+        surfaces.push(r.status === "PASS" ? {...r, status: "PLANNED_PRESENT"} : {...r, status: "PLANNED_MISSING", tranche: s.tranche ?? null});
+    }
+
+    // 이 카테고리가 보장하는 라우트의 실제 경로 — sitemap 커버리지 판정 입력.
+    const requiredRoutePaths = [];
+    for (const s of cat.required ?? []) {
+        const t = resolveRoute(s.route ?? "any");
+        if (t.kind === "PAGE") requiredRoutePaths.push(t.path);
+    }
+    for (const req of spec.siteWide?.requirements ?? []) surfaces.push(judgeSiteWide(req, [...new Set(requiredRoutePaths)]));
+    surfaces.push(...judgeNegative());
+
+    const gating = surfaces.filter((s) => s.bucket !== "planned" && s.bucket !== "conditional");
+    const failed = gating.filter((s) => FAIL_STATUSES.has(s.status));
+    results.push({
+        category: code,
+        label: cat.label ?? code,
+        shipState: cat.shipState,
+        verdict: failed.length === 0 ? "PASS" : "FAIL",
+        surfaces,
+    });
+}
+
+const snapshot = {
+    checker: "check-aeo-surfaces.mjs",
+    checkerVersion: CHECKER_VERSION,
+    /**
+     * 무엇을 잰 판정인가. `site-wide-only` 스냅샷은 **카테고리 판정이 아예 없어서** promote 입력으로 쓰면
+     * 보장 분류가 `passedFor` 에서 떨어진다(그게 맞다 — 안 잰 것을 통과로 셀 수 없다). 이 필드는 그 거절이
+     * "미충족"인지 "애초에 다른 검사"인지를 사후에 읽을 수 있게 남기는 자리다.
+     */
+    mode: siteWideOnly ? "site-wide-only" : "category",
+    guaranteesRev: spec.contractRev,
+    // 어느 출처의 잣대로 잰 판정인가 — rev 만으로는 "정본으로 쟀는지 운반본으로 쟀는지"가 안 남는다.
+    guaranteesSource: resolved.source,
+    themeCode,
+    themeVersion,
+    siteUrl,
+    checkedAt: new Date().toISOString(),
+    pagesCrawled: [...seen.keys()].sort(),
+    fetchFailures: crawled.fetchFailures,
+    verdict: results.every((r) => r.verdict === "PASS") ? "PASS" : "FAIL",
+    categories: results,
+};
+
+// ── 보고 ─────────────────────────────────────────────────────────────────────
+
+const MARK = {PASS: "✅", PLANNED_PRESENT: "✅", SKIPPED: "⏭️ ", PLANNED_MISSING: "📋"};
+console.log("");
+for (const r of results) {
+    console.log(`■ ${r.category ? `${r.category}(${r.label})` : r.label} — ${r.verdict}${r.shipState === "BLOCKED" ? " · 진열 차단(DON'T-SHIP)" : ""}`);
+    for (const s of r.surfaces) {
+        const mark = MARK[s.status] ?? "❌";
+        const tail = s.detail ? ` — ${s.detail}` : "";
+        const tranche = s.tranche ? ` [${s.tranche}]` : "";
+        console.log(`   ${mark} ${s.bucket}/${s.id}${tranche}: ${s.status}${tail}`);
+    }
+    console.log("");
+}
+
+if (outPath) {
+    mkdirSync(dirname(resolve(outPath)), {recursive: true});
+    writeFileSync(resolve(outPath), JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+    console.log(`· 검사 스냅샷 → ${outPath}`);
+    console.log(
+        siteWideOnly
+            ? "  이 스냅샷은 **promote 입력이 아니다**(카테고리 판정 0건 — 사이트 축만 잰 결과다)."
+            : "  promote 입력으로 이 파일을 그대로 넘긴다(보장 카테고리 팩은 스냅샷 없이 promote 가 거부된다).",
+    );
+} else if (!siteWideOnly) {
+    console.log("· --out 을 안 줬다 — 스냅샷을 파일로 남겨야 promote 입력으로 쓸 수 있다.");
+}
+
+const planned = results.flatMap((r) => r.surfaces.filter((s) => s.status === "PLANNED_MISSING"));
+if (planned.length) {
+    console.log(`· 예정 표면 ${planned.length}건은 실패가 아니다 — 보장표가 목표로 적어 둔 T6 작업 목록이다.`);
+}
+
+process.exit(snapshot.verdict === "PASS" ? 0 : 1);

package/contracts/aeo-surface-guarantees.json

@@ -0,0 +1,189 @@
+{
+  "$comment": "AEO 보장 표면 계약 정본(memo119 §1.0·§4.2 · T4a). 형제 계약 section-vocabulary.json 과 같은 거처·같은 관례(contractRev·기계 대조·사람 주석은 이식에서 진다)를 따른다. 어휘가 '레이아웃 규격'이 아니라 '유형별 최소 AEO/SEO 보장 계약'이라는 재정의(오너 정정 B)의 기계 형태다. 구조화 데이터에는 생김새가 없어 디자인 자유를 하나도 깎지 않고 바닥만 깔 수 있다 — 이 파일이 그 바닥이다.",
+  "contractRev": 1,
+
+  "conventions": {
+    "canonicalHere": "이 파일이 정본이다. zalkera-client/llms.txt §5.1 은 같은 계약의 **사람/AI용 운반체**이고, 대조는 zalkera-client/scripts/sync-aeo-guarantees.mjs 가 기계로 센다. 채널이 늘어도 사본을 늘리지 않는다 — AGENTS.md·콘솔 문서·MCP 는 참조 링크만 든다(memo119 §5-13).",
+    "floorNotCeiling": "보장은 바닥이지 천장이 아니다. 이 표를 못 채우는 템플릿도 만들 수 있고 적재될 수 있다 — 못 거는 것은 **그 카테고리 간판**뿐이고, 그것도 결함 판정이 아니라 진열 축의 사실 판정이다(§4.1·오너 정정 A).",
+    "whereTheWeightIs": "보장의 무게는 **라우트**에 있다. 현행 보장(Product·Organization·BlogPosting·BreadcrumbList)은 라우트·렌더러의 속성이고, 섹션이 직접 산출하는 것은 FAQPage 하나다. **섹션 어휘를 0개 쓰는 사이트도 라우트 보장은 똑같이 받는다**(§1.0-a).",
+    "verdictFromArtifact": "판정 지점은 소스가 아니라 **산출물**이다(오너 정정 C). '이 섹션을 써라'는 자유를 깎지만 '개시된 페이지에서 이 그래프가 나오는가'는 아무것도 깎지 않는다. 검사기는 storefront-template/scripts/check-aeo-surfaces.mjs 이고, 실행 자리는 promote 전 스모크 개시다.",
+    "requiredVsPlanned": "`required` 는 **이 rev 가 지금 강제하는 것**이고, `planned` 는 같은 카테고리의 목표 표면 중 **아직 우리 본보기도 못 내는 것**이다. planned 는 게이트가 아니라 T6 작업 지시서이고, 검사기는 이를 실패가 아니라 PLANNED_MISSING 으로 보고한다. `realized` 는 **그 지시가 실제로 이행됐는가**를 적는 별개 축이다 — 이행됐다고 자동으로 required 가 되지는 않는다. required 로 올리는 것은 이 표의 rev 상향이고, 그 시점은 **이행분이 개시된 산출물에 실제로 나타나는 발행 단위**다 — 코드 병합이 아니다(판정 지점이 산출물이므로 잣대의 상향 시점도 산출물이어야 한다. 병합만으로 표를 올리면 아직 재빌드 안 된 팩·구 SDK 로 빌드된 팩이 통과 못 할 요구를 받는다). rev 2 가 그 실례다: `openingHours` 는 저장 자리(백엔드 컬럼)만 섰고 `@zalkera/client` 0.9.0 미발행·템플릿 소비 0 이라, rev 2 는 T6 병합이 아니라 **client 발행 + 본보기 팩 재빌드**가 끝난 단위에서만 설 수 있다. 이 분리가 없으면 둘 중 하나를 해야 한다 — 규범을 낮추거나(보장이 거짓말이 된다), 오늘 아무도 못 거는 표를 강제하거나(카탈로그가 빈 선반이 된다).",
+    "growth": "표는 자란다. rev 상향 시 **기존 등재물의 소급 탈락은 금지**다 — 구 rev 판정은 판정 당시 rev 를 병기한 배지로 유효하게 지속되고, 신 rev 요구는 신규 등재·재promote 부터 건다. 순수 라벨 카테고리가 나중에 이 표에 편입되면 기존 등재물은 유예한다(§1.0-c). 조용한 소급은 이 설계가 죽이려던 조용한 실패의 재생산이다.",
+    "publication": "`published` 는 그 표면의 규범이 **공개 문서(llms.txt §5.1)에 이미 나가 있는가**다. false = 내부 정본에만 있다 = 아직 공표 전. 내부 정본이 앞서 있는 것은 무해하다(작업 지시서다). 그러나 **공표가 본보기를 앞지르면 안 된다** — '레시피가 본보기를 앞지르지 않는다'(§1.5-a). false→true 뒤집기는 T6 그린과 같은 발행 단위 이후이고(T4b), 대조 스크립트가 양방향으로 센다: published 인데 §5.1 에 없으면 실패, published 가 아닌데 §5.1 에 이미 있으면 **역방향 실패**(공표가 표를 앞질렀다).",
+    "categoryStorage": "카테고리는 `theme.category` 자유 문자열이다 — enum 으로 못박지 않는다(memo119 §5-6). **여기 항목이 있는 이름만** 게이트가 걸리고, 없는 이름은 순수 라벨이다(예: '미니멀'). 값 이름을 업종어가 아니라 유형어로 두는 이유는 형제 계약의 명명 규약과 같다: 업종어를 박으면 재사용이 죽는다(DOCTOR_INTRO 교훈). 그래서 예약 칸은 `BEAUTY` 가 아니라 `BOOKING` 이다 — 예약을 파는 것은 뷰티만이 아니다."
+  },
+
+  "routes": {
+    "$comment": "표면이 가리키는 라우트 어휘. LITERAL 은 그 경로 자체가 있어야 하고, INSTANCE 는 그 패턴에 맞는 **실물 한 건**을 크롤에서 찾아 검사한다(패턴 자체는 응답하지 않는다). 없는 라우트는 red 이지 스킵이 아니다 — 라우트 부재가 곧 보장 부재다.",
+    "$notASurface": "`/policies` 는 여기 없다. 그 페이지는 JSON-LD 를 **0건** 낸다 — `parsePolicies`(정책 문구 파서)만 import 할 뿐 `<JsonLd>` 를 렌더하지 않는다. 파일명 grep 이 `JsonLd` 를 문자열로 잡아 \"산출한다\"로 잘못 읽히는 자리라 명시해 둔다(실제로 그 오독이 한 번 났다). `PostalAddress` 의 거처는 `/` 의 `organizationJsonLd` 안이고 그것도 address 가 설정됐을 때만 나간다.",
+    "home": {"kind": "LITERAL", "path": "/"},
+    "cmsPage": {"kind": "INSTANCE", "pattern": "/{slug}", "note": "콘솔·시드가 만든 고정 페이지(src/app/[slug]/page.tsx). 예약 세그먼트(products·blog·c·policies·contact 등)는 인스턴스 후보에서 뺀다."},
+    "productList": {"kind": "LITERAL", "path": "/products", "note": "**T6-ⓑ 가 신설했다**(src/app/products/page.tsx · ItemList+BreadcrumbList · sitemap 등재). 레시피는 그 전부터 있었다 — llms.txt §4.1 이 이 라우트를 그린다. 개시된 사이트에 나타나는 것은 템플릿 병합 뒤 **그 팩을 다시 빌드·개시한 다음**이므로, 낡은 산출물을 크롤하면 여전히 부재로 잡힌다 — 그건 라우트 부재가 아니라 산출물이 낡은 것이다."},
+    "productDetail": {"kind": "INSTANCE", "pattern": "/products/{slug}"},
+    "productCategory": {"kind": "INSTANCE", "pattern": "/c/{slug}", "note": "**오늘 부재. 그런데 막는 것은 라우트가 아니라 데이터층이다**(2026-07-28 실측 · 설계 §0-6 에 없던 사실). 경로는 발명하지 않았다 — llms.txt §4.1 레시피가 카테고리 링크를 `/c/{slug}` 로 이미 그리고 있다. 진짜 선행은 아래 `product-category-collectionpage` 를 보라: `product_category_map` 에 **행을 넣는 경로가 전 레포 0건**이라 라우트를 지어도 어느 카테고리든 상품 0건이 된다."},
+    "blogList": {"kind": "LITERAL", "path": "/blog"},
+    "blogDetail": {"kind": "INSTANCE", "pattern": "/blog/{slug}"}
+  },
+
+  "siteWide": {
+    "$comment": "카테고리 무관 최소 기계 가독. 라우트별 그래프가 아무리 훌륭해도 크롤러가 목록을 못 받으면 발견되지 않는다.",
+    "requirements": [
+      {
+        "id": "robots",
+        "check": "ROBOTS_PRESENT",
+        "published": true,
+        "llmsMarker": "`sitemap.ts`·`robots.ts` 필수",
+        "why": "공개 카탈로그를 열고 세션·쓰기 경로만 막는다. **AI 크롤러(GPTBot·ClaudeBot 등)를 막지 않는다** — 발견 경로를 우리 손으로 닫는 일이다."
+      },
+      {
+        "id": "sitemap",
+        "check": "SITEMAP_PRESENT",
+        "published": true,
+        "llmsMarker": "`sitemap.ts`·`robots.ts` 필수",
+        "why": "존재하는 공개 라우트만 싣는다."
+      },
+      {
+        "id": "sitemap-covers-required-routes",
+        "check": "SITEMAP_COVERS",
+        "published": false,
+        "publishTranche": "T4b",
+        "llmsMarker": "sitemap 은 그 카테고리의 보장 라우트를 전부 싣는다",
+        "realized": "PARTIAL",
+        "realizedNote": "T6 이 /products 를 sitemap 에 등재했다. /blog 목록은 아직이고 카테고리는 라우트 자체가 없다 — 그래서 절반이다.",
+        "why": "현행 §5.1 의 sitemap 지시는 '홈·상품 상세·콘텐츠'라 **목록·카테고리를 모른다**(§0-11 ⓐ). 목록 라우트가 생겨도 sitemap 이 모르면 보장이 반쪽이다 — 쇼핑몰 칸이 못 서는 균열과 같은 뿌리다. 표에는 지금 넣고(작업 지시서), 공표는 본보기가 실제로 그렇게 된 뒤다."
+      },
+      {
+        "id": "absolute-urls",
+        "check": "ABSOLUTE_URLS_IN_JSONLD",
+        "published": true,
+        "llmsMarker": "절대 URL",
+        "why": "JSON-LD 의 url·item 이 상대경로면 크롤러가 해석하지 못한다."
+      }
+    ]
+  },
+
+  "negative": {
+    "$comment": "**의도적 부정 보장** — 빠뜨린 것이 아니라 결정이다. 검사기가 이것들을 '누락'으로 잡으면 안 되고, 오히려 **나타나면 실패**로 잡아야 한다.",
+    "forbiddenTypes": [
+      {
+        "type": "Review",
+        "why": "자사 사이트의 자사 후기에 별점을 붙이는 것은 self-serving reviews 정책 위반이라 제재 대상이다(memo102 §2.3). TESTIMONIALS 섹션이 jsonLd 를 안 내는 이유가 이것이다 — 어휘 12종 중 jsonLd 비-null 이 FAQ_LIST 하나뿐인 것은 미완성이 아니라 판단이다."
+      },
+      {
+        "type": "AggregateRating",
+        "scope": "ROOT_ONLY",
+        "why": "Product 안에 중첩된 AggregateRating 은 실제 후기 집계라 정상이다(productJsonLd 가 reviewCount>0 일 때만 낸다). 금지 대상은 **루트 노드로 선 AggregateRating** — 상품에 붙지 않은 별점은 자사 별점 선언이다."
+      }
+    ]
+  },
+
+  "categories": [
+    {
+      "category": "MARKETING",
+      "label": "비즈니스 홍보",
+      "shipState": "SHIPPABLE",
+      "required": [
+        {"id": "home-organization", "route": "home", "jsonLd": ["Organization", "LocalBusiness", "BeautySalon"], "ssr": true, "published": true, "llmsMarker": "홈 = `Organization`", "why": "사이트 주체가 누구인지 기계가 읽는 자리. 홈에 1회만 낸다."},
+        {"id": "cms-page-ssr", "route": "cmsPage", "jsonLd": [], "ssr": true, "published": true, "llmsMarker": "**ISR 유지.**", "why": "고정 페이지 본문이 JS 실행 없이 응답 본문에 실려야 한다. 이것이 없으면 그래프를 아무리 잘 내도 답변 엔진이 인용할 본문이 없다."}
+      ],
+      "planned": [
+        {"id": "cms-page-webpage", "route": "cmsPage", "jsonLd": ["WebPage"], "tranche": "T6-ⓐ", "realized": "DONE", "realizedNote": "T6 이 CMS 라우트에 WebPage+BreadcrumbList 를 얹었다(0건→2종).", "why": "CMS 서브페이지의 JSON-LD 는 오늘 0건이다(src/app/[slug]/page.tsx 에 JsonLd 호출 없음). 홈만 그래프를 갖고 서브페이지가 비어 있는 것이 마케팅 사이트의 실제 구멍이다."},
+        {"id": "cms-page-breadcrumb", "route": "cmsPage", "jsonLd": ["BreadcrumbList"], "tranche": "T6-ⓐ", "realized": "DONE", "realizedNote": "T6-ⓐ 와 같은 커밋.", "why": "§4.2 가 이 칸의 목표 표면에 BreadcrumbList 를 넣었는데, 오늘 BreadcrumbList 는 상품·블로그 상세에만 있다. 순수 마케팅 사이트에는 그 두 라우트가 없으므로 CMS 페이지가 유일한 거처다."}
+      ],
+      "why": "표면이 전부 홈·고정 페이지라 오늘의 렌더러로 성립한다. 시드도 오늘 이 칸을 채울 수 있다(page·page_section·menu·theme_colors)."
+    },
+    {
+      "category": "PORTFOLIO",
+      "label": "포트폴리오",
+      "shipState": "SHIPPABLE",
+      "sameAs": "MARKETING",
+      "required": [
+        {"id": "home-organization", "route": "home", "jsonLd": ["Organization", "LocalBusiness", "BeautySalon"], "ssr": true, "published": true, "llmsMarker": "홈 = `Organization`", "why": "MARKETING 과 같다."},
+        {"id": "cms-page-ssr", "route": "cmsPage", "jsonLd": [], "ssr": true, "published": true, "llmsMarker": "**ISR 유지.**", "why": "MARKETING 과 같다."}
+      ],
+      "planned": [
+        {"id": "cms-page-webpage", "route": "cmsPage", "jsonLd": ["WebPage"], "tranche": "T6-ⓐ", "why": "MARKETING 과 같다."},
+        {"id": "cms-page-breadcrumb", "route": "cmsPage", "jsonLd": ["BreadcrumbList"], "tranche": "T6-ⓐ", "why": "MARKETING 과 같다."}
+      ],
+      "why": "보장 표면이 MARKETING 과 같다. 그런데도 별 항목으로 두는 이유는 **진열 라벨이 다르기 때문**이다 — 표면이 같다고 칸을 합치면 카탈로그 탐색에서 '포트폴리오'를 찾는 사람이 못 찾는다. 같은 표면을 두 번 적는 비용은 대조 스크립트가 감당한다."
+    },
+    {
+      "category": "EVENT",
+      "label": "이벤트·프로젝트",
+      "shipState": "SHIPPABLE",
+      "required": [
+        {"id": "home-organization", "route": "home", "jsonLd": ["Organization", "LocalBusiness", "BeautySalon"], "ssr": true, "published": true, "llmsMarker": "홈 = `Organization`", "why": "MARKETING 과 같다."},
+        {"id": "cms-page-ssr", "route": "cmsPage", "jsonLd": [], "ssr": true, "published": true, "llmsMarker": "**ISR 유지.**", "why": "MARKETING 과 같다."}
+      ],
+      "conditional": [
+        {"id": "faq-page", "route": "any", "jsonLd": ["FAQPage"], "when": "SECTION_PRESENT", "section": "FAQ_LIST", "published": false, "publishTranche": "T4b", "why": "**어휘 12종 중 유일하게 섹션이 직접 산출하는 그래프**(FaqListSection.tsx:36). 조건부인 이유: 크롤한 HTML 만 보고는 'FAQ_LIST 를 안 썼다'와 'FAQ_LIST 를 썼는데 그래프가 안 나온다'를 구분할 수 없다. 그래서 검사기는 FAQPage 가 보이면 통과로, 안 보이면 SKIPPED 로 적고 **실패로 세지 않는다** — 못 세는 것을 센 척하지 않는다."}
+      ],
+      "planned": [
+        {"id": "cms-page-webpage", "route": "cmsPage", "jsonLd": ["WebPage"], "tranche": "T6-ⓐ", "why": "MARKETING 과 같다."},
+        {"id": "cms-page-breadcrumb", "route": "cmsPage", "jsonLd": ["BreadcrumbList"], "tranche": "T6-ⓐ", "why": "MARKETING 과 같다."}
+      ],
+      "why": "MARKETING 표면 + FAQ 섹션을 쓸 때의 FAQPage."
+    },
+    {
+      "category": "BOOKING",
+      "label": "예약",
+      "shipState": "SHIPPABLE",
+      "shipNote": "**축소 보장표로 등재된 상태다**(§4.2). ItemList·openingHours 를 지금 required 로 올리면 오늘 아무 팩도 이 칸을 못 걸고, 낮춰 적으면 보장이 거짓이 된다. 그래서 지금 참인 것만 강제하고 나머지는 planned 로 rev 관리한다 — rev 2 에서 required 로 올라간다. **그 rev 2 는 T6 병합 시점이 아니다**: openingHours 는 저장 자리만 서 있고 `@zalkera/client` 0.9.0(타입 추가)이 미발행이라 템플릿이 그 값을 소비하지 못해 그래프에 아무것도 안 나간다. rev 2 가 서는 단위는 **client 발행 + 본보기 팩 재빌드**다(conventions.requiredVsPlanned).",
+      "required": [
+        {"id": "home-localbusiness", "route": "home", "jsonLd": ["LocalBusiness", "BeautySalon", "HealthAndBeautyBusiness"], "ssr": true, "published": false, "publishTranche": "T4b", "why": "예약을 파는 곳은 **물리 점포**다. Organization 으로 두면 '어디로 가면 되는가'가 기계에 안 읽힌다. organizationJsonLd 는 config.businessType==BEAUTY 일 때 BeautySalon 으로 좁힌다 — 즉 이 요구는 렌더러가 아니라 **테넌트 설정**이 만족시킨다."},
+        {"id": "service-detail-product", "route": "productDetail", "jsonLd": ["Product"], "requiredChildren": ["Offer"], "ssr": true, "published": true, "llmsMarker": "상품 상세 = `Product` + variant 마다 `Offer`", "why": "시술 한 건이 상품 한 행이다. 가격이 Offer 로 나가야 '얼마인가'가 답변 엔진에 읽힌다. **이 표면은 시드가 상품을 만들 수 있어야 빈 약속이 아니다**(T1 의 products 시드가 전제)."}
+      ],
+      "planned": [
+        {"id": "service-menu-itemlist", "route": "any", "jsonLd": ["ItemList"], "tranche": "T6-ⓒ", "realized": "DONE", "realizedNote": "T6 이 SERVICE_MENU 의 ItemList 산출을 구현했고 정본 section-vocabulary.json 의 jsonLd 열이 null→ItemList(contractRev 2)로 함께 올라갔다. 여기서 required 로 올리는 것은 이 표의 **rev 2** 이고, 그 단위는 T6 병합이 아니라 **본보기 팩을 다시 빌드해 개시한 뒤**다 — 같은 rev 의 openingHours 는 거기에 더해 client 발행까지 필요하다.", "why": "시술 목록의 정위치는 **별도 라우트가 아니라 홈의 SERVICE_MENU 섹션**이다(FAQ_LIST↔FAQPage 선례). 뷰티 사이트에 /products 목록 라우트를 강제하는 것은 과잉이라 비대칭을 이렇게 해소했다(§4.2 W-F5). 구현 시 section-vocabulary.json 의 SERVICE_MENU jsonLd 열이 null→\"ItemList\" 로 올라가고 그 rev 가 동반된다."},
+        {"id": "opening-hours", "route": "home", "jsonLdProperty": "openingHours", "tranche": "T6-ⓓ", "realized": "PARTIAL", "realizedNote": "**절반이다.** 저장 자리는 섰다(백엔드 site_config 확장 + 전체교체 경로 4곳). 템플릿 렌더는 @zalkera/client 0.9.0 발행 뒤라 아직 못 나간다(발행은 2FA 라 오너 몫). 저장 자리만으로는 그래프가 안 나가므로 이 항목이 여전히 red 로 잡히는 것이 맞다.", "why": "**전 레포에 저장할 필드 자체가 없다** — 렌더러 문제가 아니라 스키마 문제다. 거처는 예약 척추 위저드의 영업시간 입력(§2.4)이고, site_config 확장 마이그레이션이 선행한다."}
+      ],
+      "why": "§4.2 예약 칸. 상세는 지금 나가고, 목록(ItemList)·영업시간은 T6 이후다."
+    },
+    {
+      "category": "COMMERCE",
+      "label": "쇼핑몰",
+      "shipState": "BLOCKED",
+      "blockedReason": "**DON'T-SHIP**(memo119 §5-11). 없는 표면을 카탈로그 간판으로 거는 것은 빈 선반이다.",
+      "unblockGate": "**정정(2026-07-28) — 'T6-ⓑ 완료 후 그린'은 거짓이다. T6-ⓑ 는 끝났는데 게이트는 안 열린다.** 목록 라우트(`/products`+ItemList)는 실제로 지어졌지만 카테고리 라우트는 못 지었고, 이유가 라우트 부재가 아니었다: **카테고리 데이터층이 없다.** 진짜 선행 조건은 상품↔카테고리 매핑을 실제로 채우고 읽는 층이다 — 도메인 모델·쓰기 경로·공개 API 필터·SDK 파라미터. 그것이 선 뒤에 라우트를 짓고, 이 검사기가 우리 팩에서 그린이면 shipState 를 SHIPPABLE 로·published 를 true 로 함께 뒤집는다.",
+      "unblockOwner": "이 사실은 설계 §0-6(라우트 부재만 기록)에 없다 — memo119 §4.2 쇼핑몰 칸의 선행 조건 서술을 갱신할지는 설계가 판정한다.",
+      "required": [
+        {"id": "product-detail", "route": "productDetail", "jsonLd": ["Product"], "requiredChildren": ["Offer"], "ssr": true, "published": true, "llmsMarker": "상품 상세 = `Product` + variant 마다 `Offer`", "why": "오늘 유일하게 나가는 커머스 표면. variant 마다 Offer 를 낸다(항상 variant 단위 판매)."},
+        {"id": "product-detail-breadcrumb", "route": "productDetail", "jsonLd": ["BreadcrumbList"], "ssr": true, "published": true, "llmsMarker": "목록·상세엔 `BreadcrumbList`", "why": "검색결과에 '홈 > 상품 > 이름' 경로가 선다."},
+        {"id": "product-list-itemlist", "route": "productList", "jsonLd": ["ItemList"], "ssr": true, "published": true,
+        "llmsMarker": "목록 라우트도 그래프를 낸다 — `ItemList`", "publishTranche": "T4b", "realized": "DONE", "realizedNote": "T6 이 /products 목록 라우트를 신설했다(404→200 · ItemList+BreadcrumbList · sitemap 등재). 이 항목은 이제 통과 가능하다 — 그래도 COMMERCE 칸이 안 열리는 이유는 같은 칸의 CollectionPage 다.", "why": "**라우트 자체가 없다.** 목록이 없으면 '이 가게가 무엇을 파는가'를 기계가 한 번에 못 받는다 — 상세 N건을 개별로 발견해야 한다. 쇼핑몰 3표면 중 2개가 비는 이유가 여기서 시작한다."},
+        {"id": "product-category-collectionpage", "route": "productCategory", "jsonLd": ["CollectionPage"], "requiredChildren": ["ItemList"], "ssr": true, "published": false, "publishTranche": "T4b", "why": "오너가 든 세 표면(카테고리·상품 상세·상품 목록) 중 마지막 하나이고, **셋 중 유일하게 아직 안 선다**. 막는 것이 라우트가 아니라는 것이 실측의 요점이다(2026-07-28): `product_category_map` 은 V9 에 테이블로 존재하지만 **INSERT 경로가 전 레포 0건**이고(유일한 코드 접촉은 카테고리 삭제 가드의 COUNT 한 줄), 도메인 모델·공개 API 필터·SDK 파라미터가 전부 없다(`PublicProductSearchRequest` = productType·keyword 뿐이고 그 KDoc 이 매핑이 채워진 뒤 확장한다고 자인한다). 즉 지금 라우트를 지으면 **어느 카테고리를 열어도 상품 0건**이 나온다 — 그건 표면을 만든 것이 아니라 빈 선반을 하나 더 세운 것이다(§4.2 빈 선반 금지)."}
+      ],
+      "why": "오너가 '쇼핑몰이라면 최소한 카테고리·상품 상세·상품 목록은 보장받아야 할 것 아니냐'고 든 그 세 표면이 이 칸의 정의다. 셋 중 하나만 나가고 있다."
+    },
+    {
+      "category": "BLOG",
+      "label": "블로그·미디어",
+      "shipState": "SHIPPABLE",
+      "seedReady": false,
+      "seedNote": "표면은 지금 서지만 **시드가 글을 못 만든다**(posts 키 없음·수요 실증 전 확장 금지·§5-5). 즉 '개시 즉시 완성'이 아니라 '개시 후 글을 쓰면 완성'이다. 카드 문구가 이 차이를 숨기면 안 된다.",
+      "required": [
+        {"id": "post-detail-blogposting", "route": "blogDetail", "jsonLd": ["BlogPosting"], "ssr": true, "published": false, "publishTranche": "T4b", "why": "글 하나가 답변 엔진에 인용되는 단위. 오늘 라이브다(blog/[slug]/page.tsx:55). §5.1 이 아직 이 규범을 안 적고 있을 뿐이라 published=false 다 — 본보기가 앞서고 레시피가 뒤따르는 방향이라 무해하다."},
+        {"id": "post-detail-breadcrumb", "route": "blogDetail", "jsonLd": ["BreadcrumbList"], "ssr": true, "published": true, "llmsMarker": "목록·상세엔 `BreadcrumbList`", "why": "상세 라우트의 경로 표시."},
+        {"id": "post-list-ssr", "route": "blogList", "jsonLd": [], "ssr": true, "published": true, "llmsMarker": "**ISR 유지.**", "why": "목록 라우트는 오늘 있다(force-static·revalidate 300)."}
+      ],
+      "planned": [
+        {"id": "post-list-itemlist", "route": "blogList", "jsonLd": ["ItemList", "Blog"], "tranche": "T6", "realized": "DONE_DATA_PENDING", "realizedNote": "T6 이 /blog 목록에 BreadcrumbList 를 얹었다. ItemList 는 글이 0건이라 안 나간다 — **의도**다(negative 규율과 같다: 페이지에 없는 것을 JSON-LD 에 쓰지 않는다). 시드가 글을 못 만드는 한 이 항목의 그린은 데이터에 달려 있다.", "why": "목록 라우트는 있는데 그래프가 없다. 상품 목록과 같은 형태의 구멍이라 같이 메우는 것이 맞다."}
+      ],
+      "why": "§4.2 블로그·미디어 칸. 표면은 지금·시드는 나중."
+    }
+  ],
+
+  "notRegistered": [
+    {
+      "category": "COMMUNITY",
+      "label": "커뮤니티",
+      "why": "**등재하지 않는다**(§4.2 DON'T). 게시판 축 자체가 미래탐색이라 보장할 표면도 만들 데이터도 없다. 빈 항목으로 넣으면 이 파일이 '준비 중' 간판을 하나 더 세우는 셈이라, 침묵이 아니라 명시적 부재로 적는다."
+    }
+  ],
+
+  "catalogRequirements": {
+    "$comment": "이 표를 게이트로 쓸 때 **카탈로그 UI 가 반드시 갖춰야 하는 것**(§4.1 W-F4). 계약 파일에 적는 이유: 이 요건이 빠지면 진열 게이트가 조용히 '부드러운 강제'로 변질돼 오너 정정 A(다양성 우선)를 뒤로 어긴다.",
+    "categoryAgnosticSurface": "카탈로그 탐색 UI 는 **카테고리 무관 표면(전체 목록·검색)을 반드시 갖는다.** 없으면 무카테고리 = 사실상 비가시가 되고, '어떤 템플릿이든 적재될 수 있다'가 말뿐이 된다.",
+    "noDefectWording": "미충족은 **결함이 아니라 다른 칸**이다. 카드 문구에 '~불가'·'미지원' 류 결함 어투를 쓰지 않는다(§3.9·오너 정정 D — 편집 축은 가격 단계이지 손실이 아니다)."
+  }
+}

package/lib/site-crawl.mjs

@@ -0,0 +1,227 @@
+/**
+ * 개시된 사이트를 훑는 최소 크롤러 — `snapshot-preview.mjs`(memo116 §3)와
+ * `check-aeo-surfaces.mjs`(memo119 T5)가 **같은 사본**을 쓴다.
+ *
+ * 원래 이 코드는 snapshot-preview 안에 살았다. 보장 검사기가 "산출물을 크롤해 판정한다"(memo119 오너
+ * 전제 C)를 구현하려면 같은 훑기가 필요한데, 복사하면 두 크롤러가 조용히 갈라진다 — 한쪽이 라우트 분류를
+ * 고치고 다른 쪽이 안 고치면 "미리보기에는 나오는데 검사기는 못 보는 페이지"가 생긴다. 그래서 옮겼다.
+ *
+ * ── 외부 의존 0 ────────────────────────────────────────────────────────────
+ * 이 레포의 팩 스크립트가 zip 을 손으로 쓰는 것과 같은 규율이다. HTML 은 정규식 태그 스캐너로,
+ * 다운로드는 Node 내장 `fetch` 로 처리한다. 상대하는 마크업이 **우리가 만든 것**이라(임의 웹이 아니다)
+ * 파서를 들일 만큼의 다양성이 없다.
+ */
+
+// ── HTML 태그 스캐너 ─────────────────────────────────────────────────────────
+
+export const TAG_RE = /<([a-zA-Z][-\w:]*)((?:\s+[-\w:@.]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*(\/?)>/g;
+const ATTR_RE = /([-\w:@.]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+export const DROP = Symbol("drop-element");
+
+export function parseAttrs(text) {
+    const attrs = [];
+    if (!text) return attrs;
+    ATTR_RE.lastIndex = 0;
+    let m;
+    while ((m = ATTR_RE.exec(text)) !== null) {
+        attrs.push([m[1], m[2] ?? m[3] ?? m[4] ?? null]);
+    }
+    return attrs;
+}
+
+export const attrOf = (attrs, name) => {
+    const hit = attrs.find(([k]) => k.toLowerCase() === name);
+    return hit ? hit[1] : undefined;
+};
+
+/**
+ * `parseAttrs` 는 원문 조각을 **이스케이프된 그대로** 돌려준다. 여기서 `&` 를 다시 인코딩하면
+ * `&amp;` → `&amp;amp;` 가 되어 화면에 `&amp;` 가 그대로 보인다(심의 실측 — alt 텍스트가 깨졌다).
+ * 그래서 값은 손대지 않고, 따옴표만 원문에 없던 경우에 대비해 감싼다.
+ */
+export function serializeAttrs(attrs) {
+    return attrs.map(([k, v]) => (v === null ? ` ${k}` : ` ${k}="${String(v).replace(/"/g, "&quot;")}"`)).join("");
+}
+
+/**
+ * 태그 단위 변환. `transform` 이 [DROP] 을 돌려주면 그 **여는 태그만** 지운다 — 대상은 `<meta>`·`<link>`
+ * 같은 void 요소뿐이라 내용은 애초에 없다.
+ */
+export function rewriteTags(html, transform) {
+    return html.replace(TAG_RE, (full, name, attrText, selfClose) => {
+        const attrs = parseAttrs(attrText);
+        const out = transform(name.toLowerCase(), attrs);
+        if (out === DROP) return "";
+        if (!out) return full;
+        return `<${name}${serializeAttrs(out)}${selfClose ? " /" : ""}>`;
+    });
+}
+
+/** HTML 엔티티만 푼다 — 속성값에서 URL 을 꺼낼 때 필요한 최소셋. */
+export const unescapeAttr = (v) =>
+    v.replace(/&amp;/g, "&").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+
+// ── 라우트 정책 ──────────────────────────────────────────────────────────────
+
+export const segmentsOf = (path) => path.split("/").filter(Boolean);
+
+/**
+ * 정적으로 성립할 수 없는 기능 라우트. 세션·쓰기·결제다.
+ * validator 의 `SEO_EXCLUDE_SEGMENTS`(ISR 게이트 제외 목록)와 같은 어휘를 쓴다 — 그쪽이
+ * "정당하게 동적인 인터랙티브 경로"로 이미 판정해 둔 집합이고, 둘이 갈리면 한쪽이 틀린 것이다.
+ */
+export const FUNCTIONAL_SEGMENTS = new Set([
+    "api", "cart", "checkout", "mypage", "account", "login", "auth", "orders", "payment",
+]);
+
+/**
+ * 테넌트 **식별정보 표시면**. 미리보기 스냅샷은 이걸 크롤하지 않는다(가릴 것만 많다).
+ * 보장 검사기는 다르다 — 아무것도 공개하지 않고 판정만 하므로 여기를 훑어도 유출 표면이 없다.
+ * 그래서 이 집합은 상수가 아니라 **호출자가 고르는 값**이다.
+ */
+export const IDENTITY_ROUTES = new Set(["/policies", "/contact"]);
+
+/** 페이지가 아닌 기계용 파일. */
+export const MACHINE_FILES = new Set(["/robots.txt", "/sitemap.xml", "/favicon.ico"]);
+
+/** 이 확장자는 페이지가 아니라 자산이다(경로만 보고 판정할 때). */
+export const ASSET_EXT = new Set([
+    ".css", ".js", ".mjs", ".map", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".avif",
+    ".ico", ".woff", ".woff2", ".ttf", ".otf", ".mp4", ".webm", ".json", ".xml", ".txt",
+]);
+
+/**
+ * URL 하나를 분류하는 함수를 만든다. `origin` 은 크롤 대상 오리진, `skipRoutes` 는 페이지지만
+ * 훑지 않을 경로 집합(미리보기=식별정보 라우트, 검사기=빈 집합).
+ */
+export function makeClassifier({origin, skipRoutes = IDENTITY_ROUTES}) {
+    return function classify(rawUrl, fromPath) {
+        let u;
+        try {
+            u = new URL(unescapeAttr(rawUrl), origin + fromPath);
+        } catch {
+            return {kind: "opaque"};
+        }
+        if (u.protocol !== "http:" && u.protocol !== "https:") return {kind: "opaque"}; // mailto:·tel:·data:
+        if (u.origin !== origin) return {kind: "external", url: u};
+        const path = u.pathname;
+        if (path.startsWith("/_next/") || path.startsWith("/media/")) return {kind: "asset", url: u};
+        if (ASSET_EXT.has(extnameOf(path))) return {kind: "asset", url: u};
+        if (MACHINE_FILES.has(path)) return {kind: "blocked", url: u};
+        const segs = segmentsOf(path);
+        if (segs.some((s) => FUNCTIONAL_SEGMENTS.has(s))) return {kind: "blocked", url: u};
+        if (skipRoutes.has(path.replace(/\/+$/, "") || "/")) return {kind: "blocked", url: u};
+        return {kind: "page", path: path.replace(/\/+$/, "") || "/"};
+    };
+}
+
+/** `node:path` 의 extname 과 같되 소문자로. 경로 문자열만 상대하므로 의존을 안 들인다. */
+function extnameOf(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot <= 0 ? "" : base.slice(dot).toLowerCase();
+}
+
+// ── 링크 수집 ────────────────────────────────────────────────────────────────
+
+const splitSrcset = (v) => (v ? v.split(",").map((p) => p.trim().split(/\s+/)[0]).filter(Boolean) : []);
+
+/**
+ * 페이지 HTML 에서 나가는 링크·자산을 수집한다(변형 없음 — 1차 통과).
+ * `sink` 는 blocked·external 을 받는 선택 콜백(미리보기 리포트가 쓴다).
+ */
+export function collectLinks(html, fromPath, classify, sink = {}) {
+    const links = new Set();
+    const assetUrls = new Set();
+    const absOrNull = (raw) => {
+        if (!raw) return null;
+        const c = classify(raw, fromPath);
+        return c.kind === "asset" ? c.url.toString() : null;
+    };
+    rewriteTags(html, (tag, attrs) => {
+        const push = (raw) => {
+            if (!raw) return;
+            const c = classify(raw, fromPath);
+            if (c.kind === "page") links.add(c.path);
+            else if (c.kind === "asset") assetUrls.add(c.url.toString());
+            else if (c.kind === "blocked") sink.blocked?.(c.url.pathname);
+            else if (c.kind === "external") sink.external?.(c.url.origin);
+        };
+        if (tag === "a") push(attrOf(attrs, "href"));
+        if (tag === "link") {
+            const rel = (attrOf(attrs, "rel") ?? "").toLowerCase();
+            if (rel.includes("stylesheet") || rel.includes("icon")) assetUrls.add(absOrNull(attrOf(attrs, "href")));
+        }
+        if (tag === "img" || tag === "source" || tag === "video" || tag === "audio") {
+            const src = absOrNull(attrOf(attrs, "src"));
+            if (src) assetUrls.add(src);
+            for (const s of splitSrcset(attrOf(attrs, "srcset"))) {
+                const abs = absOrNull(s);
+                if (abs) assetUrls.add(abs);
+            }
+        }
+        return null;
+    });
+    assetUrls.delete(null);
+    return {links, assetUrls};
+}
+
+// ── 크롤 ─────────────────────────────────────────────────────────────────────
+
+/**
+ * 링크를 따라 페이지 HTML 을 모은다. **JS 를 실행하지 않는다** — 그것이 요점이다: 여기서 보이는
+ * 것이 크롤러·답변 엔진이 실제로 받는 것이고, 하이드레이션 뒤에만 나타나는 내용은 보장이 아니다.
+ *
+ * 반환: `{pages: Map<routePath, html>, assetUrls: Set, fetchFailures: string[], blocked: Set, external: Set}`
+ */
+export async function crawlPages({
+    origin,
+    entryPath = "/",
+    extraRoutes = [],
+    maxPages = 60,
+    classify,
+    userAgent = "zalkera-crawler",
+    onPage = null,
+}) {
+    const pages = new Map();
+    const assetUrls = new Set();
+    const fetchFailures = [];
+    const blocked = new Set();
+    const external = new Set();
+    const sink = {blocked: (p) => blocked.add(p), external: (o) => external.add(o)};
+
+    const queue = [entryPath, ...extraRoutes.map((r) => (r.startsWith("/") ? r : `/${r}`))];
+    const seen = new Set();
+
+    while (queue.length > 0 && pages.size < maxPages) {
+        const path = queue.shift();
+        if (seen.has(path)) continue;
+        seen.add(path);
+
+        const url = origin + (path === "/" ? "/" : path);
+        let res;
+        try {
+            res = await fetch(url, {headers: {"user-agent": userAgent}});
+        } catch (e) {
+            fetchFailures.push(`${url} — ${e.message}`);
+            continue;
+        }
+        if (!res.ok) {
+            fetchFailures.push(`${url} — HTTP ${res.status}`);
+            continue;
+        }
+        if (!(res.headers.get("content-type") ?? "").includes("html")) {
+            fetchFailures.push(`${url} — HTML 이 아닙니다(${res.headers.get("content-type")})`);
+            continue;
+        }
+        const html = await res.text();
+        pages.set(path, html);
+        onPage?.(path);
+
+        const collected = collectLinks(html, path, classify, sink);
+        for (const l of collected.links) if (!seen.has(l)) queue.push(l);
+        for (const a of collected.assetUrls) assetUrls.add(a);
+    }
+
+    return {pages, assetUrls, fetchFailures, blocked, external};
+}

package/llms.txt

@@ -407,6 +407,20 @@ if (booking.orderNo) {                  // status=PENDING
 - ❌ **`getMediaUrl` 의 presigned URL 을 마크업·JSON-LD 에 직접 쓰지 마라.** 수 분 뒤 죽는다 — ISR 로 캐시된
   HTML 안에서(상세 revalidate 300s) 서명이 먼저 만료돼 이미지가 깨지고, 크롤러가 캐시하면 JSON-LD 도 죽는다.
 
+**이 절의 규범은 기계로 잴 수 있다.** 이 패키지는 판정 잣대인 **보장표**를
+`@zalkera/client/contracts/aeo-surface-guarantees.json` 으로 함께 배송한다(정본은 잘커라 백엔드에 있고 이것은
+그 발행 산출물이다 — 내용이 갈라지지 않게 발행 전 기계가 대조한다). **검사기 자신도 이 패키지가 싣고
+온다**(bin `zalkera-aeo-check`) — 그 표를 읽어 **개시된 사이트를 크롤해** 판정하므로, 소스가 아니라
+산출물이 잣대다. 어떤 스택으로 짰든 같은 조건이다:
+
+```bash
+npx zalkera-aeo-check https://개시된사이트 --category BOOKING   # 0=통과 · 1=미충족 · 2=실행 불가
+npx zalkera-aeo-check https://개시된사이트 --site-wide-only     # 보장 주장이 없는 사이트(사이트 축만)
+# 템플릿에서 출발한 프로젝트라면 같은 검사기를 이렇게도 부른다:
+npm run check:aeo -- https://개시된사이트 --category BOOKING
+npm run check:aeo -- --print-guarantees                        # 잣대 해석만 확인(크롤 없음)
+```
+
 - ❌ 배송 전(PAID)에 후기 작성 시도 → `NOT_DELIVERED_YET`(409). ✅ 주문이 **DELIVERED 이상**일 때만
   버튼을 낸다(상태로 게이트). orderItemId 는 주문 상세 items[].id 에서만 얻는다 — 상품 상세엔 없다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zalkera/client",
-    "version": "0.10.0",
+    "version": "0.12.0",
     "description": "zalkera 헤드리스 CMS 공개 API 클라이언트 (테넌트 사이트용)",
     "license": "MIT",
     "author": "Credium Co., Ltd.",
@@ -19,17 +19,26 @@
     "homepage": "https://zalkera.com",
     "files": [
         "dist",
-        "llms.txt"
+        "llms.txt",
+        "contracts",
+        "bin",
+        "lib"
     ],
     "main": "./dist/index.cjs",
     "module": "./dist/index.js",
     "types": "./dist/index.d.ts",
+    "bin": {
+        "zalkera-aeo-check": "./bin/check-aeo-surfaces.mjs"
+    },
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js",
             "require": "./dist/index.cjs"
-        }
+        },
+        "./contracts/aeo-surface-guarantees.json": "./contracts/aeo-surface-guarantees.json",
+        "./bin/check-aeo-surfaces.mjs": "./bin/check-aeo-surfaces.mjs",
+        "./lib/site-crawl.mjs": "./lib/site-crawl.mjs"
     },
     "scripts": {
         "build": "tsup",