@sonordev/contracts 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.2.0
+
+A minor release: one new entry, `@sonordev/contracts/proposal-sitemap`. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/proposal-sitemap`**: how a website proposal's site plan counts its pages, so the app that writes a proposal, the API that checks it and the page that shows it state the same numbers.
+  - `countSitemapPlan(plan)` counts core pages, the plan's own pages, re-published articles, pages carried over and pages added, each address once.
+  - `sitemapTransformation(plan)` decides whether the plan's before-and-after comparison shows. It shows only when the build is bigger than today; a rebuild that keeps the same pages never reads as "N → 0".
+  - `normalizeSitemapLabels(labels)` keeps the words a plan may use for pages that aren't services sold to industries.
+  - `proposalPageCountIssues(sections)` and `describePageCountIssue(issue)` find page and URL counts stated in a proposal's headline, summary, pricing and plan copy that don't match the plan.
+
 ## 2.1.1
 
 - Docs only: the README names the Sonor API and the dashboard where it named internal repositories. No code changes.

package/README.md

@@ -22,6 +22,7 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/site-cache` | The cache tags a site's Sonor fetches carry and the revalidation route's path, payload and ping | site-kit tags and serves the route, the Sonor API calls it |
 | `@sonordev/contracts/site-edit` | Edit on page: the messages between a framed site and the dashboard, trusted origins, how a slot is found on the page | site-kit's overlay, the dashboard's visual editor |
 | `@sonordev/contracts/portfolio` | Where a portfolio number comes from and which may headline; the live-frame message | the Sonor API, Signal, agency-site-kit |
+| `@sonordev/contracts/proposal-sitemap` | How a proposal's site plan counts its pages, when its before-and-after comparison may show, and whether the page counts stated elsewhere in the proposal add up | the Sonor API, Signal's proposal writer, the dashboard's proposal pages |
 | `@sonordev/contracts/voice` | The house voice's contraction rule. `findUncontracted` and `contractText` find and apply full forms that should be contractions; `findContracted` finds the contractions a question-form heading should expand | anything that checks or rewrites copy: Sonor's APIs and dashboard |
 
 ## The voice contract
@@ -135,6 +136,55 @@ pinned by a test, so changing it later is a visible change.
   "*", "_" and masked text before it are skipped, so "Now: let us look at it."
   contracts.
 
+## The proposal-sitemap contract
+
+A website proposal's site plan lists the pages a build delivers: core pages
+(Home, About, Contact), top-level pages, and the pages under them. Its numbers
+are what a buyer reads first, so they're computed here and never taken from
+prose.
+
+- **`countSitemapPlan(plan)`** returns `core`, `architecture` (the plan's own
+  pages), `articles` (existing posts re-published with the build), `full`
+  (all three), `existing` (pages carried over) and `added` (new pages). Each
+  address counts once: core pages first, then each top-level page and the
+  pages under it. A row without a slug always counts.
+- **`sitemapTransformation(plan)`** returns the before-and-after comparison
+  to show (`{ before, after }`), or `null`. It shows only when the plan states
+  today's count and the build is bigger. A rebuild that keeps the same pages
+  isn't a before and after, so an after-count of zero, or one no bigger than
+  today's, hides it.
+- **`normalizeSitemapLabels(labels)`** keeps the words a plan may use for its
+  own pages when they aren't services sold to industries: `architecture` (the
+  heading), `pillar` (a top-level page) and `child` (a page under one). Each is
+  one line of 1 to 40 characters.
+- **`proposalPageCountIssues(sections)`** lists the page and URL counts a
+  proposal states in its headline, summary, pricing and plan copy that match
+  nothing the plan or its measured evidence adds up to.
+  `describePageCountIssue(issue)` puts one in a sentence for the person
+  reviewing it.
+
+```ts
+import { countSitemapPlan, proposalPageCountIssues } from '@sonordev/contracts/proposal-sitemap'
+
+countSitemapPlan({
+  corePages: [{ slug: '/' }, { slug: '/about/' }, { slug: '/locations/' }],
+  pages: [{ slug: '/locations/', children: [{ name: 'Springfield' }, { name: 'Shelbyville' }] }],
+}).full
+// 5: the top-level /locations/ page is the core one, counted once
+
+proposalPageCountIssues([
+  { type: 'GlassHero', props: { stats: [{ value: '12', label: 'pages rebuilt' }] } },
+  { type: 'SitemapPlan', props: { pages: [{ slug: '/' }, { slug: '/about/' }] } },
+])
+// [{ section: 'GlassHero', field: 'stats[0]', claimed: 12, unit: 'page', text: '12 pages', planned: 2 }]
+```
+
+It reads "N pages", "an N-page site", "N existing URLs" and up to three words
+between the number and "page" or "URL". A count written in words ("five
+pages") isn't read, and a count of pages that aren't in the plan (say, a
+competitor's) is reported like any other; the issues are for a person to look
+at, not edits to apply.
+
 ## Why it exists
 
 A rule that lives in several copies is how two of them end up disagreeing.

package/dist/proposal-sitemap.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @sonordev/contracts/proposal-sitemap — how a proposal's site plan is counted (v1)
+ *
+ * Single source of truth for the numbers a website proposal's site plan
+ * (the `SitemapPlan` block) states: how many pages the build has, when the
+ * "before → after" comparison may show, which custom labels the block may
+ * carry, and whether page counts written elsewhere in the proposal agree with
+ * the plan. The proposal generator stamps them, the Sonor API checks them and
+ * the dashboard renders them, so the headline, the plan and the price can't
+ * each state a different number.
+ *
+ * Why it exists: the numbers in a plan are what a buyer reads first, and a
+ * count written by a language model can't be trusted to add up. A rebuild
+ * that keeps every page must never read as a loss ("24 → 0 pages"), one
+ * address listed twice must not count twice, and the headline must not state
+ * a number the plan doesn't. Counts are computed here, never taken from prose.
+ */
+/** Bump on breaking changes to how a plan is counted. */
+export declare const PROPOSAL_SITEMAP_CONTRACT_VERSION: 1;
+/**
+ * A count the plan states: a non-negative whole number, as a number or a
+ * numeric string. Anything else is no count at all (undefined), never 0.
+ */
+export declare function sitemapCount(v: unknown): number | undefined;
+/**
+ * The address a plan row stands for, in one shape: lowercase, no scheme or
+ * host, no query or fragment, a leading slash and no trailing one ("/" for the
+ * home page). Undefined for a row without a slug; such a row always counts,
+ * since nothing proves it repeats another.
+ */
+export declare function sitemapPageKey(slug: unknown): string | undefined;
+export interface SitemapPlanCounts {
+    /** Core pages (Home, About, Contact and the like), each address once. */
+    core: number;
+    /**
+     * The plan's own pages: top-level pages plus the pages under them, minus
+     * any address already counted as a core page.
+     */
+    architecture: number;
+    /** Existing articles re-published with the build (the plan's `blog.count`). */
+    articles: number;
+    /** Everything the client gets: core + architecture + articles. */
+    full: number;
+    /**
+     * Pages that exist today and carry over (status rebuild, optimize or
+     * migrate, plus the re-published articles).
+     */
+    existing: number;
+    /** Pages the build adds (status new, or no status). */
+    added: number;
+}
+/**
+ * Count a site plan's pages, each address once. Core pages are counted
+ * first, then each top-level page and the pages under it; a row whose
+ * address was already counted is skipped. Rows without a slug always count.
+ */
+export declare function countSitemapPlan(props: unknown): SitemapPlanCounts;
+export interface SitemapTransformationCounts {
+    /** Today's count, as the plan states it. */
+    before: number;
+    /** The build's count. */
+    after: number;
+}
+/**
+ * The before → after comparison a plan may show, or null when it must not
+ * show. It shows only when the plan states today's count and the build is
+ * bigger. A missing after-count falls back to the plan's own pages (then its
+ * `totalPages`); an after-count of zero, or one no bigger than today's, hides
+ * the comparison. A rebuild that keeps the same pages isn't a before and after.
+ */
+export declare function sitemapTransformation(props: unknown): SitemapTransformationCounts | null;
+/**
+ * Words a plan uses for its own pages, for a business whose pages aren't
+ * services sold to industries (communities and towns, practice areas,
+ * locations). Each replaces one default: `architecture` the heading
+ * ("Service Architecture"), `pillar` a top-level page ("Service pillar"),
+ * `child` a page under it ("Industry page"). Singular, title case.
+ */
+export interface SitemapPlanLabels {
+    architecture?: string;
+    pillar?: string;
+    child?: string;
+}
+/** The longest a label may be. */
+export declare const SITEMAP_LABEL_MAX = 40;
+/**
+ * Keep only usable labels: strings of 1 to {@link SITEMAP_LABEL_MAX}
+ * characters on one line, whitespace collapsed, no angle brackets. Undefined
+ * when none survive, so a plan without labels reads the defaults.
+ */
+export declare function normalizeSitemapLabels(raw: unknown): SitemapPlanLabels | undefined;
+export type PageCountUnit = 'page' | 'url';
+export interface PageCountClaim {
+    /** The number stated. */
+    value: number;
+    /** Whether it counts pages or URLs. */
+    unit: PageCountUnit;
+    /** The words that make the claim, e.g. "27 existing URLs". */
+    text: string;
+    /** Where the claim starts in the text. */
+    index: number;
+}
+/**
+ * Every page or URL count stated in a piece of text. A number that's part of
+ * a name ("Troy 7 Apartments get pages of their own") isn't a count.
+ */
+export declare function findPageCountClaims(text: unknown): PageCountClaim[];
+export interface PageCountIssue {
+    /** The block the claim is in, e.g. "GlassHero". */
+    section: string;
+    /** Where in the block, e.g. "stats[0]" or "tiers[0].features[1]". */
+    field: string;
+    /** The number stated. */
+    claimed: number;
+    unit: PageCountUnit;
+    /** The words that make the claim. */
+    text: string;
+    /** The page count the plan adds up to. */
+    planned: number;
+}
+/**
+ * Page and URL counts a proposal states that match nothing its site plan or
+ * its measured evidence adds up to. A stated count passes when it equals any
+ * of: the plan's full, core, own, article, carried-over or added page count;
+ * the plan's stated before-count; or the measured URL and page counts the
+ * evidence blocks carry. Empty when the proposal has no site plan.
+ */
+export declare function proposalPageCountIssues(sections: unknown): PageCountIssue[];
+/** One plain sentence for a person reviewing the proposal before it's sent. */
+export declare function describePageCountIssue(issue: PageCountIssue): string;

package/dist/proposal-sitemap.js

@@ -0,0 +1,212 @@
+'use strict';
+
+// src/contracts/proposal-sitemap.ts
+var PROPOSAL_SITEMAP_CONTRACT_VERSION = 1;
+function isRecord(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function list(v) {
+  return Array.isArray(v) ? v : [];
+}
+function sitemapCount(v) {
+  const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : void 0;
+}
+function sitemapPageKey(slug) {
+  if (typeof slug !== "string") return void 0;
+  let s = slug.trim().toLowerCase();
+  if (!s) return void 0;
+  s = s.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/, "");
+  s = s.split(/[?#]/)[0];
+  if (!s.startsWith("/")) s = `/${s}`;
+  s = s.replace(/\/{2,}/g, "/").replace(/\/+$/, "");
+  return s || "/";
+}
+var EXISTING_STATUSES = /* @__PURE__ */ new Set(["rebuild", "optimize", "migrate"]);
+function countSitemapPlan(props) {
+  const p = isRecord(props) ? props : {};
+  const seen = /* @__PURE__ */ new Set();
+  let existing = 0;
+  let added = 0;
+  const take = (node) => {
+    if (!isRecord(node)) return false;
+    const key = sitemapPageKey(node.slug);
+    if (key !== void 0) {
+      if (seen.has(key)) return false;
+      seen.add(key);
+    }
+    if (typeof node.status === "string" && EXISTING_STATUSES.has(node.status)) existing++;
+    else added++;
+    return true;
+  };
+  let core = 0;
+  for (const node of list(p.corePages)) if (take(node)) core++;
+  let architecture = 0;
+  for (const pillar of list(p.pages)) {
+    if (take(pillar)) architecture++;
+    if (!isRecord(pillar)) continue;
+    for (const child of list(pillar.children)) if (take(child)) architecture++;
+  }
+  const articles = isRecord(p.blog) ? sitemapCount(p.blog.count) ?? 0 : 0;
+  return {
+    core,
+    architecture,
+    articles,
+    full: core + architecture + articles,
+    existing: existing + articles,
+    added
+  };
+}
+function sitemapTransformation(props) {
+  const p = isRecord(props) ? props : {};
+  const t = p.transformation;
+  if (!isRecord(t)) return null;
+  const before = sitemapCount(isRecord(t.before) ? t.before.count : void 0);
+  if (before === void 0) return null;
+  const planned = countSitemapPlan(p).architecture;
+  const after = sitemapCount(isRecord(t.after) ? t.after.count : void 0) ?? (planned > 0 ? planned : sitemapCount(p.totalPages) ?? 0);
+  if (after <= 0 || after <= before) return null;
+  return { before, after };
+}
+var SITEMAP_LABEL_MAX = 40;
+var LABEL_KEYS = ["architecture", "pillar", "child"];
+function normalizeSitemapLabels(raw) {
+  if (!isRecord(raw)) return void 0;
+  const out = {};
+  for (const key of LABEL_KEYS) {
+    const v = raw[key];
+    if (typeof v !== "string") continue;
+    if (/[\u0000-\u0008\u000a-\u001f\u007f<>]/.test(v)) continue;
+    const s = v.replace(/\s+/g, " ").trim();
+    if (s && s.length <= SITEMAP_LABEL_MAX) out[key] = s;
+  }
+  return Object.keys(out).length ? out : void 0;
+}
+var CLAIM_RE = /(?<![\d$.,/])(\d{1,5})(?![\d.,/%])(?:[\s-]+(?:[a-z'’&]+[\s-]+){0,3}?)(pages?|urls?)\b/gi;
+var CAPITALIZED_BEFORE_RE = /(?<![\w'’])[A-Z][\w'’.&-]*\s+$/;
+function numberInName(before) {
+  const m = before.match(CAPITALIZED_BEFORE_RE);
+  if (!m) return false;
+  const lead = before.slice(0, m.index);
+  if (/\n\s*$/.test(lead)) return false;
+  const trimmed = lead.replace(/\s+$/, "");
+  return trimmed !== "" && !/[.!?:]$/.test(trimmed);
+}
+function findPageCountClaims(text) {
+  if (typeof text !== "string" || !text) return [];
+  const claims = [];
+  for (const m of text.matchAll(CLAIM_RE)) {
+    if (numberInName(text.slice(0, m.index ?? 0))) continue;
+    claims.push({
+      value: Number(m[1]),
+      unit: m[2].toLowerCase().startsWith("url") ? "url" : "page",
+      text: m[0],
+      index: m.index ?? 0
+    });
+  }
+  return claims;
+}
+function claimFields(section) {
+  const props = isRecord(section.props) ? section.props : {};
+  switch (section.type) {
+    case "GlassHero": {
+      const fields = [["title", props.title], ["subtitle", props.subtitle]];
+      list(props.stats).forEach((st, i) => {
+        if (!isRecord(st)) return;
+        const value = typeof st.value === "number" || typeof st.value === "string" ? String(st.value) : "";
+        fields.push([`stats[${i}]`, `${value} ${typeof st.label === "string" ? st.label : ""}`]);
+      });
+      return fields;
+    }
+    case "ExecutiveSummary":
+      return [["content", props.content]];
+    case "GlassPricing": {
+      const fields = [["note", props.note]];
+      list(props.tiers).forEach((tier, i) => {
+        if (!isRecord(tier)) return;
+        fields.push([`tiers[${i}].name`, tier.name], [`tiers[${i}].description`, tier.description]);
+        list(tier.features).forEach((f, j) => fields.push([`tiers[${i}].features[${j}]`, f]));
+      });
+      return fields;
+    }
+    case "SitemapPlan": {
+      const strategy = isRecord(props.strategy) ? props.strategy : {};
+      return [
+        ["title", props.title],
+        ["subtitle", props.subtitle],
+        ["strategy.headline", strategy.headline],
+        ["strategy.lead", strategy.lead]
+      ];
+    }
+    default:
+      return [];
+  }
+}
+function proposalPageCountIssues(sections) {
+  const secs = list(sections).filter(isRecord);
+  const plan = secs.find((s) => s.type === "SitemapPlan");
+  if (!plan) return [];
+  const planProps = isRecord(plan.props) ? plan.props : {};
+  const counts = countSitemapPlan(planProps);
+  const known = /* @__PURE__ */ new Set([
+    counts.full,
+    counts.core,
+    counts.architecture,
+    counts.articles,
+    counts.existing,
+    counts.added,
+    counts.core + counts.architecture
+  ]);
+  const transformation = isRecord(planProps.transformation) ? planProps.transformation : {};
+  const before = sitemapCount(isRecord(transformation.before) ? transformation.before.count : void 0);
+  if (before !== void 0) known.add(before);
+  for (const s of secs) {
+    const props = isRecord(s.props) ? s.props : {};
+    if (s.type === "MigrationSafetyPlan") {
+      const urls = sitemapCount(props.urlCount);
+      if (urls !== void 0) known.add(urls);
+    }
+    if (s.type === "ContentDepth" && isRecord(props.ledger)) {
+      const measured = sitemapCount(props.ledger.beforePages);
+      if (measured !== void 0) known.add(measured);
+    }
+  }
+  const issues = [];
+  for (const s of secs) {
+    for (const [field, text] of claimFields(s)) {
+      for (const claim of findPageCountClaims(text)) {
+        if (known.has(claim.value)) continue;
+        issues.push({
+          section: String(s.type),
+          field,
+          claimed: claim.value,
+          unit: claim.unit,
+          text: claim.text,
+          planned: counts.full
+        });
+      }
+    }
+  }
+  return issues;
+}
+var SECTION_NAMES = {
+  GlassHero: "The headline",
+  ExecutiveSummary: "The summary",
+  GlassPricing: "The pricing",
+  SitemapPlan: "The site plan"
+};
+function describePageCountIssue(issue) {
+  const where = SECTION_NAMES[issue.section] ?? `The ${issue.section} section`;
+  return `${where} says "${issue.text}", but the site plan adds up to ${issue.planned} ${issue.planned === 1 ? "page" : "pages"}.`;
+}
+
+exports.PROPOSAL_SITEMAP_CONTRACT_VERSION = PROPOSAL_SITEMAP_CONTRACT_VERSION;
+exports.SITEMAP_LABEL_MAX = SITEMAP_LABEL_MAX;
+exports.countSitemapPlan = countSitemapPlan;
+exports.describePageCountIssue = describePageCountIssue;
+exports.findPageCountClaims = findPageCountClaims;
+exports.normalizeSitemapLabels = normalizeSitemapLabels;
+exports.proposalPageCountIssues = proposalPageCountIssues;
+exports.sitemapCount = sitemapCount;
+exports.sitemapPageKey = sitemapPageKey;
+exports.sitemapTransformation = sitemapTransformation;

package/dist/proposal-sitemap.mjs

@@ -0,0 +1,201 @@
+// src/contracts/proposal-sitemap.ts
+var PROPOSAL_SITEMAP_CONTRACT_VERSION = 1;
+function isRecord(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function list(v) {
+  return Array.isArray(v) ? v : [];
+}
+function sitemapCount(v) {
+  const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : void 0;
+}
+function sitemapPageKey(slug) {
+  if (typeof slug !== "string") return void 0;
+  let s = slug.trim().toLowerCase();
+  if (!s) return void 0;
+  s = s.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/, "");
+  s = s.split(/[?#]/)[0];
+  if (!s.startsWith("/")) s = `/${s}`;
+  s = s.replace(/\/{2,}/g, "/").replace(/\/+$/, "");
+  return s || "/";
+}
+var EXISTING_STATUSES = /* @__PURE__ */ new Set(["rebuild", "optimize", "migrate"]);
+function countSitemapPlan(props) {
+  const p = isRecord(props) ? props : {};
+  const seen = /* @__PURE__ */ new Set();
+  let existing = 0;
+  let added = 0;
+  const take = (node) => {
+    if (!isRecord(node)) return false;
+    const key = sitemapPageKey(node.slug);
+    if (key !== void 0) {
+      if (seen.has(key)) return false;
+      seen.add(key);
+    }
+    if (typeof node.status === "string" && EXISTING_STATUSES.has(node.status)) existing++;
+    else added++;
+    return true;
+  };
+  let core = 0;
+  for (const node of list(p.corePages)) if (take(node)) core++;
+  let architecture = 0;
+  for (const pillar of list(p.pages)) {
+    if (take(pillar)) architecture++;
+    if (!isRecord(pillar)) continue;
+    for (const child of list(pillar.children)) if (take(child)) architecture++;
+  }
+  const articles = isRecord(p.blog) ? sitemapCount(p.blog.count) ?? 0 : 0;
+  return {
+    core,
+    architecture,
+    articles,
+    full: core + architecture + articles,
+    existing: existing + articles,
+    added
+  };
+}
+function sitemapTransformation(props) {
+  const p = isRecord(props) ? props : {};
+  const t = p.transformation;
+  if (!isRecord(t)) return null;
+  const before = sitemapCount(isRecord(t.before) ? t.before.count : void 0);
+  if (before === void 0) return null;
+  const planned = countSitemapPlan(p).architecture;
+  const after = sitemapCount(isRecord(t.after) ? t.after.count : void 0) ?? (planned > 0 ? planned : sitemapCount(p.totalPages) ?? 0);
+  if (after <= 0 || after <= before) return null;
+  return { before, after };
+}
+var SITEMAP_LABEL_MAX = 40;
+var LABEL_KEYS = ["architecture", "pillar", "child"];
+function normalizeSitemapLabels(raw) {
+  if (!isRecord(raw)) return void 0;
+  const out = {};
+  for (const key of LABEL_KEYS) {
+    const v = raw[key];
+    if (typeof v !== "string") continue;
+    if (/[\u0000-\u0008\u000a-\u001f\u007f<>]/.test(v)) continue;
+    const s = v.replace(/\s+/g, " ").trim();
+    if (s && s.length <= SITEMAP_LABEL_MAX) out[key] = s;
+  }
+  return Object.keys(out).length ? out : void 0;
+}
+var CLAIM_RE = /(?<![\d$.,/])(\d{1,5})(?![\d.,/%])(?:[\s-]+(?:[a-z'’&]+[\s-]+){0,3}?)(pages?|urls?)\b/gi;
+var CAPITALIZED_BEFORE_RE = /(?<![\w'’])[A-Z][\w'’.&-]*\s+$/;
+function numberInName(before) {
+  const m = before.match(CAPITALIZED_BEFORE_RE);
+  if (!m) return false;
+  const lead = before.slice(0, m.index);
+  if (/\n\s*$/.test(lead)) return false;
+  const trimmed = lead.replace(/\s+$/, "");
+  return trimmed !== "" && !/[.!?:]$/.test(trimmed);
+}
+function findPageCountClaims(text) {
+  if (typeof text !== "string" || !text) return [];
+  const claims = [];
+  for (const m of text.matchAll(CLAIM_RE)) {
+    if (numberInName(text.slice(0, m.index ?? 0))) continue;
+    claims.push({
+      value: Number(m[1]),
+      unit: m[2].toLowerCase().startsWith("url") ? "url" : "page",
+      text: m[0],
+      index: m.index ?? 0
+    });
+  }
+  return claims;
+}
+function claimFields(section) {
+  const props = isRecord(section.props) ? section.props : {};
+  switch (section.type) {
+    case "GlassHero": {
+      const fields = [["title", props.title], ["subtitle", props.subtitle]];
+      list(props.stats).forEach((st, i) => {
+        if (!isRecord(st)) return;
+        const value = typeof st.value === "number" || typeof st.value === "string" ? String(st.value) : "";
+        fields.push([`stats[${i}]`, `${value} ${typeof st.label === "string" ? st.label : ""}`]);
+      });
+      return fields;
+    }
+    case "ExecutiveSummary":
+      return [["content", props.content]];
+    case "GlassPricing": {
+      const fields = [["note", props.note]];
+      list(props.tiers).forEach((tier, i) => {
+        if (!isRecord(tier)) return;
+        fields.push([`tiers[${i}].name`, tier.name], [`tiers[${i}].description`, tier.description]);
+        list(tier.features).forEach((f, j) => fields.push([`tiers[${i}].features[${j}]`, f]));
+      });
+      return fields;
+    }
+    case "SitemapPlan": {
+      const strategy = isRecord(props.strategy) ? props.strategy : {};
+      return [
+        ["title", props.title],
+        ["subtitle", props.subtitle],
+        ["strategy.headline", strategy.headline],
+        ["strategy.lead", strategy.lead]
+      ];
+    }
+    default:
+      return [];
+  }
+}
+function proposalPageCountIssues(sections) {
+  const secs = list(sections).filter(isRecord);
+  const plan = secs.find((s) => s.type === "SitemapPlan");
+  if (!plan) return [];
+  const planProps = isRecord(plan.props) ? plan.props : {};
+  const counts = countSitemapPlan(planProps);
+  const known = /* @__PURE__ */ new Set([
+    counts.full,
+    counts.core,
+    counts.architecture,
+    counts.articles,
+    counts.existing,
+    counts.added,
+    counts.core + counts.architecture
+  ]);
+  const transformation = isRecord(planProps.transformation) ? planProps.transformation : {};
+  const before = sitemapCount(isRecord(transformation.before) ? transformation.before.count : void 0);
+  if (before !== void 0) known.add(before);
+  for (const s of secs) {
+    const props = isRecord(s.props) ? s.props : {};
+    if (s.type === "MigrationSafetyPlan") {
+      const urls = sitemapCount(props.urlCount);
+      if (urls !== void 0) known.add(urls);
+    }
+    if (s.type === "ContentDepth" && isRecord(props.ledger)) {
+      const measured = sitemapCount(props.ledger.beforePages);
+      if (measured !== void 0) known.add(measured);
+    }
+  }
+  const issues = [];
+  for (const s of secs) {
+    for (const [field, text] of claimFields(s)) {
+      for (const claim of findPageCountClaims(text)) {
+        if (known.has(claim.value)) continue;
+        issues.push({
+          section: String(s.type),
+          field,
+          claimed: claim.value,
+          unit: claim.unit,
+          text: claim.text,
+          planned: counts.full
+        });
+      }
+    }
+  }
+  return issues;
+}
+var SECTION_NAMES = {
+  GlassHero: "The headline",
+  ExecutiveSummary: "The summary",
+  GlassPricing: "The pricing",
+  SitemapPlan: "The site plan"
+};
+function describePageCountIssue(issue) {
+  const where = SECTION_NAMES[issue.section] ?? `The ${issue.section} section`;
+  return `${where} says "${issue.text}", but the site plan adds up to ${issue.planned} ${issue.planned === 1 ? "page" : "pages"}.`;
+}
+
+export { PROPOSAL_SITEMAP_CONTRACT_VERSION, SITEMAP_LABEL_MAX, countSitemapPlan, describePageCountIssue, findPageCountClaims, normalizeSitemapLabels, proposalPageCountIssues, sitemapCount, sitemapPageKey, sitemapTransformation };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.1.1",
-  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics and the house voice's contraction rule. Pure functions, no dependencies.",
+  "version": "2.2.0",
+  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule and how a proposal's site plan counts its pages. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -85,6 +85,11 @@
       "import": "./dist/voice.mjs",
       "require": "./dist/voice.js"
     },
+    "./proposal-sitemap": {
+      "types": "./dist/proposal-sitemap.d.ts",
+      "import": "./dist/proposal-sitemap.mjs",
+      "require": "./dist/proposal-sitemap.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {