@sonordev/contracts 1.0.0

package/dist/portfolio.mjs

@@ -0,0 +1,114 @@
+// src/contracts/portfolio.ts
+var FRAME_READY_MESSAGE = "sonor:frame-ready";
+function isFrameReadyMessage(data) {
+  return !!data && typeof data === "object" && data.type === FRAME_READY_MESSAGE && data.v === 1;
+}
+var PORTFOLIO_CONTRACT_VERSION = 1;
+var LIGHTHOUSE_RE = /lighthouse/i;
+function isLighthouseKpi(kpi) {
+  return LIGHTHOUSE_RE.test(kpi.label || "");
+}
+function curateHeroKpis(kpis) {
+  const business = kpis.filter((k) => !isLighthouseKpi(k));
+  const lighthouse = kpis.filter(isLighthouseKpi);
+  if (lighthouse.length <= 1) return kpis;
+  const allPerfect = lighthouse.length >= 4 && lighthouse.every((k) => k.value === 100);
+  const summary = allPerfect ? {
+    ...lighthouse[0],
+    label: "Lighthouse, all 4 categories",
+    description: "Perfect scores across performance, SEO, accessibility, and best practices."
+  } : lighthouse.find((k) => /performance/i.test(k.label)) ?? lighthouse[0];
+  return [...business, summary];
+}
+var PORTFOLIO_KPI_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/portfolio-kpi.v1.json",
+  title: "KpiLike",
+  description: "The subset of a portfolio KPI tile the Lighthouse-collapse policy reads.",
+  type: "object",
+  required: ["label", "value"],
+  properties: {
+    label: { type: "string" },
+    value: { type: "number" },
+    description: { type: "string" },
+    source: { enum: ["measured", "reported", "estimated"] },
+    reportedBy: {
+      type: "object",
+      required: ["name", "organization", "date"],
+      properties: {
+        name: { type: "string", minLength: 1 },
+        role: { type: "string" },
+        organization: { type: "string", minLength: 1 },
+        date: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" }
+      }
+    }
+  },
+  // A reported number is only valid with someone named behind it.
+  if: { properties: { source: { const: "reported" } }, required: ["source"] },
+  then: { required: ["reportedBy"] },
+  additionalProperties: true
+};
+var METRIC_SOURCES = ["measured", "reported", "estimated"];
+var ISO_DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+var MONTHS = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December"
+];
+function isMetricSource(value) {
+  return typeof value === "string" && METRIC_SOURCES.includes(value);
+}
+function metricSourceProblem(metric) {
+  if (metric.source === void 0 || metric.source === null) return null;
+  if (!isMetricSource(metric.source)) return `source must be one of ${METRIC_SOURCES.join(", ")}`;
+  if (metric.source !== "reported") return null;
+  const by = metric.reportedBy;
+  if (!by || typeof by !== "object") {
+    return "a reported number needs reportedBy: who reported it, where they work, and when";
+  }
+  if (typeof by.name !== "string" || !by.name.trim()) return "reportedBy.name is required";
+  if (typeof by.organization !== "string" || !by.organization.trim()) {
+    return "reportedBy.organization is required";
+  }
+  if (typeof by.date !== "string" || !ISO_DAY_RE.test(by.date) || Number.isNaN(Date.parse(by.date))) {
+    return "reportedBy.date must be a real day, YYYY-MM-DD";
+  }
+  if (by.role !== void 0 && typeof by.role !== "string") return "reportedBy.role must be text";
+  return null;
+}
+function isHeadlineMetric(metric) {
+  if (metric.source === "measured") return true;
+  return metric.source === "reported" && metricSourceProblem(metric) === null;
+}
+function metricSourceLabel(source) {
+  if (source === "measured") return "Measured";
+  if (source === "reported") return "Client-reported";
+  if (source === "estimated") return "Estimated";
+  return null;
+}
+function formatAttribution(by) {
+  const [year, month, day] = by.date.split("-").map(Number);
+  const when = MONTHS[month - 1] ? `${MONTHS[month - 1]} ${day}, ${year}` : by.date;
+  return [`Reported by ${by.name.trim()}`, by.role?.trim(), by.organization.trim(), when].filter(Boolean).join(", ");
+}
+function shortAttribution(by) {
+  return `per ${by.organization.trim()}`;
+}
+function carryReportedMetrics(previous, next, keyOf) {
+  const norm = (metric) => String(keyOf(metric) ?? "").trim().toLowerCase();
+  const reported = (previous ?? []).filter((m) => m?.source === "reported");
+  const taken = new Set(reported.map(norm));
+  const generated = (next ?? []).filter((m) => m && m.source !== "reported" && !taken.has(norm(m)));
+  return [...reported, ...generated];
+}
+
+export { FRAME_READY_MESSAGE, METRIC_SOURCES, PORTFOLIO_CONTRACT_VERSION, PORTFOLIO_KPI_JSON_SCHEMA, carryReportedMetrics, curateHeroKpis, formatAttribution, isFrameReadyMessage, isHeadlineMetric, isLighthouseKpi, isMetricSource, metricSourceLabel, metricSourceProblem, shortAttribution };

package/dist/seo-meta.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @sonordev/contracts/seo-meta — generated title/description quality contract (v1)
+ *
+ * Single source of truth for "is this machine-generated seo_pages.managed_title
+ * / managed_meta_description fit to ship?". site-kit applies it at render time
+ * (getManagedMetadata falls back to the page's own title/description), and
+ * signal-api imports it (`src/shared/utils/seo-meta-quality.util.ts`) to gate
+ * every generated title before it's written, so the two can't disagree.
+ *
+ * Why it exists (2026-09-15): Signal's meta generator used the raw domain as
+ * the brand whenever it could not resolve one, so ~500 managed titles across
+ * 20+ projects shipped as "Apartments for Rent | abbeyglenapts.com", were
+ * hard-cut at 60 chars ("… | reinhartheatingandcooli"), lost the suffix to a
+ * word-boundary cut ("Contact Reinhart Heating and Cooling |"), or had the
+ * model rebuild a brand out of the domain ("About SSO Shkosh Apartments | SSO
+ * Shkosh" for ssoshkoshapts.com — the brand is SS Oshkosh Apartments). Sites
+ * rendered them verbatim.
+ *
+ * Every rule derives from the site's own identity (its hosts and brand), so
+ * there is no list of bad strings to maintain. Pure string logic — no I/O, no
+ * Node built-ins.
+ */
+/** Bump on breaking changes to what counts as a problem. */
+export declare const SEO_META_CONTRACT_VERSION: 1;
+/** Who the site is. Hosts come from the project/site config, the brand from the resolved business name — never from the domain. */
+export interface MetaIdentity {
+    /** The site's brand, e.g. "SS Oshkosh Apartments". */
+    brand?: string | null;
+    /** Other correct spellings of the brand. */
+    brandAliases?: Array<string | null | undefined>;
+    /** Hosts the site answers on, in any spelling (URL, www, port). */
+    hosts?: Array<string | null | undefined>;
+}
+export type TitleProblem = 'empty' | 'placeholder' | 'dangling-separator' | 'hostname' | 'mangled-brand';
+export type DescriptionProblem = 'empty' | 'hostname' | 'mangled-brand' | 'truncated';
+export type SuffixProblem = 'hostname' | 'mangled-brand';
+/** "https://www.AbbeyGlenApts.com:443/x" → "abbeyglenapts.com". Null for anything that isn't a host (no dot, or words). */
+export declare function metaHost(value: string | null | undefined): string | null;
+/** True when the text names the brand (an alias, or either one's core) word for word. */
+export declare function namesBrand(text: string, id: MetaIdentity): boolean;
+/** Everything after the last " | ", or null when the title has no suffix. */
+export declare function titleSuffix(title: string): string | null;
+/** Everything before the last " | ". */
+export declare function stripTitleSuffix(title: string): string;
+/**
+ * Why a title's brand suffix (the part after the last " | ") can't ship, or
+ * null when it can. Exposed so a generator can replace a bad suffix with the
+ * real brand instead of discarding the whole title.
+ */
+export declare function suffixProblem(suffix: string, id: MetaIdentity): SuffixProblem | null;
+/** Why a managed title can't ship, or null when it can. */
+export declare function titleProblem(title: string | null | undefined, id: MetaIdentity, opts?: {
+    path?: string | null;
+}): TitleProblem | null;
+/** Why a managed meta description can't ship, or null when it can. */
+export declare function descriptionProblem(description: string | null | undefined, id: MetaIdentity): DescriptionProblem | null;

package/dist/seo-meta.js

@@ -0,0 +1,155 @@
+'use strict';
+
+// src/contracts/seo-meta.ts
+var SEO_META_CONTRACT_VERSION = 1;
+var TITLE_SEPARATOR = " | ";
+var DANGLING_TAIL = /[|,\-–—:;·•]\s*$/;
+var TRAILING_FUNCTION_WORD = /\s(?:for|of|and|or|in|on|at|to|with|from|by|a|an|the|your|our|that|&)$/i;
+var MIN_HOST_FRAGMENT = 8;
+var MIN_NAME_LETTERS = 6;
+var lettersOf = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "");
+var wordsOf = (s) => ` ${s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim()} `;
+function metaHost(value) {
+  if (!value || typeof value !== "string" || /\s/.test(value.trim())) return null;
+  const s = value.trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, "").split(/[/?#]/)[0].split(":")[0].replace(/\.+$/, "").replace(/^www\./, "");
+  return s.includes(".") ? s : null;
+}
+function hostsOf(id) {
+  const out = /* @__PURE__ */ new Set();
+  for (const h of id.hosts ?? []) {
+    const host = metaHost(h);
+    if (host) out.add(host);
+  }
+  return [...out];
+}
+function labelsOf(id) {
+  return hostsOf(id).map((h) => lettersOf(h.split(".")[0])).filter((l) => l.length >= MIN_NAME_LETTERS);
+}
+function brandCore(name) {
+  let s = name.replace(/^the\s+/i, "").trim();
+  let prev;
+  do {
+    prev = s;
+    s = s.replace(/[\s,]+(?:apartments|apts|llc|inc|co|corp|ltd|company)\.?$/i, "").trim();
+  } while (s !== prev);
+  return s;
+}
+function brandVariants(id) {
+  const out = [];
+  for (const raw of [id.brand, ...id.brandAliases ?? []]) {
+    const name = typeof raw === "string" ? raw.replace(/\s+/g, " ").trim() : "";
+    if (!name) continue;
+    out.push(name);
+    const core = brandCore(name);
+    if (core && core !== name) out.push(core);
+  }
+  return out;
+}
+function nameVariants(id) {
+  return brandVariants(id).filter((v) => metaHost(v) === null);
+}
+function namesBrand(text, id) {
+  const words = wordsOf(text);
+  return brandVariants(id).some((v) => wordsOf(v).trim() !== "" && words.includes(wordsOf(v)));
+}
+function titleSuffix(title) {
+  const t = title.trim();
+  const i = t.lastIndexOf(TITLE_SEPARATOR);
+  return i > 0 ? t.slice(i + TITLE_SEPARATOR.length).trim() : null;
+}
+function stripTitleSuffix(title) {
+  const t = title.trim();
+  const i = t.lastIndexOf(TITLE_SEPARATOR);
+  return i > 0 ? t.slice(0, i).trim() : t;
+}
+function namesHost(text, id) {
+  const lower = text.toLowerCase();
+  const brands = brandVariants(id).map((b) => b.toLowerCase());
+  return hostsOf(id).some((host) => lower.includes(host) && !brands.some((b) => b.includes(host)));
+}
+function endsOnTruncatedHost(text, id) {
+  const tokens = text.trim().split(/[\s|,()[\]]+/);
+  const last = (tokens[tokens.length - 1] ?? "").replace(/^[^a-z0-9]+/i, "");
+  if (!last || last !== last.toLowerCase()) return false;
+  const stem = lettersOf(last.split(".")[0]);
+  return stem.length >= MIN_HOST_FRAGMENT && labelsOf(id).some((l) => l.startsWith(stem));
+}
+function occurrences(hay, needle, step = needle.length) {
+  let n = 0;
+  for (let i = hay.indexOf(needle); i !== -1; i = hay.indexOf(needle, i + step)) n++;
+  return n;
+}
+function respellsBrand(text, id) {
+  const letters = lettersOf(text);
+  const words = wordsOf(text);
+  return nameVariants(id).some((v) => {
+    const vl = lettersOf(v);
+    if (vl.length < MIN_NAME_LETTERS) return false;
+    const vw = wordsOf(v);
+    return occurrences(letters, vl) > occurrences(words, vw, vw.length - 1);
+  });
+}
+function gluesHostLabel(text, id) {
+  const variants = nameVariants(id);
+  if (!variants.length) return false;
+  const labels = labelsOf(id);
+  return text.split(/[\s|,()[\]:;]+/).some((token) => {
+    const tl = lettersOf(token);
+    return tl.length >= MIN_NAME_LETTERS && labels.includes(tl) && !variants.some((v) => wordsOf(v).includes(wordsOf(token)));
+  });
+}
+function suffixProblem(suffix, id) {
+  const s = suffix.trim();
+  if (!s) return null;
+  if (namesHost(s, id) || endsOnTruncatedHost(s, id)) return "hostname";
+  const variants = nameVariants(id);
+  if (!variants.length) return null;
+  if (respellsBrand(s, id) || gluesHostLabel(s, id)) return "mangled-brand";
+  if (/\s/.test(s)) return null;
+  const sl = lettersOf(s);
+  const fromLabel = sl.length >= MIN_NAME_LETTERS && labelsOf(id).some((l) => l.startsWith(sl));
+  const sw = wordsOf(brandCore(s));
+  const isBrand = variants.some((v) => {
+    const vw = wordsOf(brandCore(v));
+    return vw.startsWith(sw) || sw.startsWith(vw);
+  });
+  return fromLabel && !isBrand ? "mangled-brand" : null;
+}
+function isPlaceholder(title, path) {
+  const t = title.trim();
+  if (!path) return false;
+  const strip = (s) => s.replace(/\/+$/, "") || "/";
+  if (t.startsWith("/") && strip(t.toLowerCase()) === strip(path.trim().toLowerCase())) return true;
+  return strip(path.trim()) === "/" && /^(home|index|untitled)$/i.test(t);
+}
+function titleProblem(title, id, opts = {}) {
+  const t = (title ?? "").trim();
+  if (!t) return "empty";
+  if (isPlaceholder(t, opts.path)) return "placeholder";
+  if (DANGLING_TAIL.test(t)) return "dangling-separator";
+  if (namesHost(t, id) || endsOnTruncatedHost(t, id)) return "hostname";
+  const suffix = titleSuffix(t);
+  if (suffix !== null) {
+    const problem = suffixProblem(suffix, id);
+    if (problem) return problem;
+  }
+  if (respellsBrand(t, id) || gluesHostLabel(t, id)) return "mangled-brand";
+  return null;
+}
+function descriptionProblem(description, id) {
+  const d = (description ?? "").trim();
+  if (!d) return "empty";
+  if (namesHost(d, id)) return "hostname";
+  if (respellsBrand(d, id) || gluesHostLabel(d, id)) return "mangled-brand";
+  if (DANGLING_TAIL.test(d) || TRAILING_FUNCTION_WORD.test(d)) return "truncated";
+  return null;
+}
+
+exports.SEO_META_CONTRACT_VERSION = SEO_META_CONTRACT_VERSION;
+exports.descriptionProblem = descriptionProblem;
+exports.metaHost = metaHost;
+exports.namesBrand = namesBrand;
+exports.stripTitleSuffix = stripTitleSuffix;
+exports.suffixProblem = suffixProblem;
+exports.titleProblem = titleProblem;
+exports.titleSuffix = titleSuffix;

package/dist/seo-meta.mjs

@@ -0,0 +1,146 @@
+// src/contracts/seo-meta.ts
+var SEO_META_CONTRACT_VERSION = 1;
+var TITLE_SEPARATOR = " | ";
+var DANGLING_TAIL = /[|,\-–—:;·•]\s*$/;
+var TRAILING_FUNCTION_WORD = /\s(?:for|of|and|or|in|on|at|to|with|from|by|a|an|the|your|our|that|&)$/i;
+var MIN_HOST_FRAGMENT = 8;
+var MIN_NAME_LETTERS = 6;
+var lettersOf = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "");
+var wordsOf = (s) => ` ${s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim()} `;
+function metaHost(value) {
+  if (!value || typeof value !== "string" || /\s/.test(value.trim())) return null;
+  const s = value.trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, "").split(/[/?#]/)[0].split(":")[0].replace(/\.+$/, "").replace(/^www\./, "");
+  return s.includes(".") ? s : null;
+}
+function hostsOf(id) {
+  const out = /* @__PURE__ */ new Set();
+  for (const h of id.hosts ?? []) {
+    const host = metaHost(h);
+    if (host) out.add(host);
+  }
+  return [...out];
+}
+function labelsOf(id) {
+  return hostsOf(id).map((h) => lettersOf(h.split(".")[0])).filter((l) => l.length >= MIN_NAME_LETTERS);
+}
+function brandCore(name) {
+  let s = name.replace(/^the\s+/i, "").trim();
+  let prev;
+  do {
+    prev = s;
+    s = s.replace(/[\s,]+(?:apartments|apts|llc|inc|co|corp|ltd|company)\.?$/i, "").trim();
+  } while (s !== prev);
+  return s;
+}
+function brandVariants(id) {
+  const out = [];
+  for (const raw of [id.brand, ...id.brandAliases ?? []]) {
+    const name = typeof raw === "string" ? raw.replace(/\s+/g, " ").trim() : "";
+    if (!name) continue;
+    out.push(name);
+    const core = brandCore(name);
+    if (core && core !== name) out.push(core);
+  }
+  return out;
+}
+function nameVariants(id) {
+  return brandVariants(id).filter((v) => metaHost(v) === null);
+}
+function namesBrand(text, id) {
+  const words = wordsOf(text);
+  return brandVariants(id).some((v) => wordsOf(v).trim() !== "" && words.includes(wordsOf(v)));
+}
+function titleSuffix(title) {
+  const t = title.trim();
+  const i = t.lastIndexOf(TITLE_SEPARATOR);
+  return i > 0 ? t.slice(i + TITLE_SEPARATOR.length).trim() : null;
+}
+function stripTitleSuffix(title) {
+  const t = title.trim();
+  const i = t.lastIndexOf(TITLE_SEPARATOR);
+  return i > 0 ? t.slice(0, i).trim() : t;
+}
+function namesHost(text, id) {
+  const lower = text.toLowerCase();
+  const brands = brandVariants(id).map((b) => b.toLowerCase());
+  return hostsOf(id).some((host) => lower.includes(host) && !brands.some((b) => b.includes(host)));
+}
+function endsOnTruncatedHost(text, id) {
+  const tokens = text.trim().split(/[\s|,()[\]]+/);
+  const last = (tokens[tokens.length - 1] ?? "").replace(/^[^a-z0-9]+/i, "");
+  if (!last || last !== last.toLowerCase()) return false;
+  const stem = lettersOf(last.split(".")[0]);
+  return stem.length >= MIN_HOST_FRAGMENT && labelsOf(id).some((l) => l.startsWith(stem));
+}
+function occurrences(hay, needle, step = needle.length) {
+  let n = 0;
+  for (let i = hay.indexOf(needle); i !== -1; i = hay.indexOf(needle, i + step)) n++;
+  return n;
+}
+function respellsBrand(text, id) {
+  const letters = lettersOf(text);
+  const words = wordsOf(text);
+  return nameVariants(id).some((v) => {
+    const vl = lettersOf(v);
+    if (vl.length < MIN_NAME_LETTERS) return false;
+    const vw = wordsOf(v);
+    return occurrences(letters, vl) > occurrences(words, vw, vw.length - 1);
+  });
+}
+function gluesHostLabel(text, id) {
+  const variants = nameVariants(id);
+  if (!variants.length) return false;
+  const labels = labelsOf(id);
+  return text.split(/[\s|,()[\]:;]+/).some((token) => {
+    const tl = lettersOf(token);
+    return tl.length >= MIN_NAME_LETTERS && labels.includes(tl) && !variants.some((v) => wordsOf(v).includes(wordsOf(token)));
+  });
+}
+function suffixProblem(suffix, id) {
+  const s = suffix.trim();
+  if (!s) return null;
+  if (namesHost(s, id) || endsOnTruncatedHost(s, id)) return "hostname";
+  const variants = nameVariants(id);
+  if (!variants.length) return null;
+  if (respellsBrand(s, id) || gluesHostLabel(s, id)) return "mangled-brand";
+  if (/\s/.test(s)) return null;
+  const sl = lettersOf(s);
+  const fromLabel = sl.length >= MIN_NAME_LETTERS && labelsOf(id).some((l) => l.startsWith(sl));
+  const sw = wordsOf(brandCore(s));
+  const isBrand = variants.some((v) => {
+    const vw = wordsOf(brandCore(v));
+    return vw.startsWith(sw) || sw.startsWith(vw);
+  });
+  return fromLabel && !isBrand ? "mangled-brand" : null;
+}
+function isPlaceholder(title, path) {
+  const t = title.trim();
+  if (!path) return false;
+  const strip = (s) => s.replace(/\/+$/, "") || "/";
+  if (t.startsWith("/") && strip(t.toLowerCase()) === strip(path.trim().toLowerCase())) return true;
+  return strip(path.trim()) === "/" && /^(home|index|untitled)$/i.test(t);
+}
+function titleProblem(title, id, opts = {}) {
+  const t = (title ?? "").trim();
+  if (!t) return "empty";
+  if (isPlaceholder(t, opts.path)) return "placeholder";
+  if (DANGLING_TAIL.test(t)) return "dangling-separator";
+  if (namesHost(t, id) || endsOnTruncatedHost(t, id)) return "hostname";
+  const suffix = titleSuffix(t);
+  if (suffix !== null) {
+    const problem = suffixProblem(suffix, id);
+    if (problem) return problem;
+  }
+  if (respellsBrand(t, id) || gluesHostLabel(t, id)) return "mangled-brand";
+  return null;
+}
+function descriptionProblem(description, id) {
+  const d = (description ?? "").trim();
+  if (!d) return "empty";
+  if (namesHost(d, id)) return "hostname";
+  if (respellsBrand(d, id) || gluesHostLabel(d, id)) return "mangled-brand";
+  if (DANGLING_TAIL.test(d) || TRAILING_FUNCTION_WORD.test(d)) return "truncated";
+  return null;
+}
+
+export { SEO_META_CONTRACT_VERSION, descriptionProblem, metaHost, namesBrand, stripTitleSuffix, suffixProblem, titleProblem, titleSuffix };

package/dist/seo-pages.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @sonordev/contracts/seo-pages — seo_pages row resolution contract (v1)
+ *
+ * Single source of truth for choosing ONE seo_pages row when a (project_id,
+ * path/url) lookup matches several, and for scoping a project's rows to one
+ * host. site-kit (`@sonordev/site-kit/seo/pages/contract`), sonor-api
+ * (`src/modules/seo/seo-page-resolve.util.ts`) and signal-api
+ * (`src/shared/utils/seo-page-pick.util.ts`) all import this; none keeps a
+ * copy.
+ *
+ * seo_pages identity became (project_id, site, url) in sonor-api migration
+ * 20260702150000_seo_pages_per_site_identity.sql: a multi-site project (one
+ * Sonor project hosting many domains) keeps one row PER SUB-SITE HOST for
+ * shared paths like `/` or `/contact`. Any path/url lookup can therefore match
+ * several rows — `.single()`/`.maybeSingle()` error on them (PGRST116) — so
+ * read one deterministically via `pickSeoPageRow` instead.
+ *
+ * Pure data logic over row shapes (no I/O, no Node built-ins).
+ */
+/** Bump on breaking changes to the row-pick preference order. */
+export declare const SEO_PAGES_CONTRACT_VERSION: 1;
+/**
+ * Single source of truth for "this seo_pages row is still live" — apply as
+ * `.or(LIVE_SEO_PAGE_FILTER)` (PostgREST, in either API) on any read that
+ * represents the site's CURRENT content to the outside world.
+ *
+ * Retired pages are kept as tombstones (status='removed') so their history and
+ * redirects survive, which means every public read has to opt out of them
+ * explicitly. Three reads in llms-content.service.ts never did, and the sitemap
+ * sync's removal flag was write-only for as long as the code existed: on
+ * 2026-09-20 upforge.io's llms.txt — the file handed straight to AI crawlers —
+ * was 32% dead URLs, advertising service areas in Atlanta, Detroit and Tampa
+ * that the business has never served.
+ *
+ * Null-safe by design: `status` is nullable with an 'active' default, so a row
+ * whose status was explicitly nulled stays live rather than vanishing from the
+ * index. A bare `.eq('status','active')` would drop it, and `.neq(...,'removed')`
+ * would too, because PostgREST evaluates NULL comparisons as NULL.
+ */
+export declare const LIVE_SEO_PAGE_FILTER = "status.is.null,status.eq.active";
+/** Minimal row shape `pickSeoPageRow` reads — callers pass their own richer rows. */
+export interface SeoPageRowLike {
+    site?: string | null;
+    updated_at?: string | null;
+}
+/**
+ * pickSeoPageRow — choose ONE row among per-site seo_pages rows sharing a
+ * path/url. Preference order:
+ *  1. exact `site` match (www-insensitive) when the caller knows the host
+ *  2. unattributed legacy row (site IS NULL)
+ *  3. the project's primary-domain row
+ *  4. most recently updated
+ */
+export declare function pickSeoPageRow<T extends SeoPageRowLike>(rows: T[], opts?: {
+    site?: string | null;
+    primaryHost?: string | null;
+}): T | null;
+/**
+ * matchSitemapEntryRow — choose the existing row a given host's write or read
+ * reconciles into. Lives here beside `pickSeoPageRow` because it is the same
+ * decision from the other direction: `pickSeoPageRow` answers "which row do I
+ * show when I don't have to care about the host", this answers "which row
+ * BELONGS to this host".
+ *
+ *  - site-tagged: the same host's row; else CLAIM an unattributed (NULL-site)
+ *    legacy row — a write stamps it with this host. Never matches another
+ *    host's row (this was the site flip-flop bug: shared paths collapsed into
+ *    one row whose site tag swung to the last syncer). `null` means the path
+ *    is not this host's, which is a real answer, not a miss.
+ *  - site-less: deterministic pick via pickSeoPageRow (NULL-site → primary
+ *    domain → most recent).
+ *
+ * The single matcher for every by-path caller — sitemap registration, GSC
+ * metrics sync, runtime page registration, and the llms.txt page index
+ * (`scopeSeoPagesToSite`). Do not fork this rule.
+ */
+export declare function matchSitemapEntryRow<T extends SeoPageRowLike>(candidates: T[], site: string | null, primaryHost: string | null): T | null;
+/**
+ * scopeSeoPagesToSite — reduce a project's seo_pages rows to the ONE page set
+ * that belongs to `site`, keeping at most one row per path.
+ *
+ * Why this exists: a multi-site project (one Sonor project hosting many
+ * domains — bd-aec.com plus 48 sibling domains, truepowersystems.com plus its
+ * state microsites) holds one row PER HOST for shared paths like `/` and
+ * `/terms`. Any project-wide read that dedupes by path alone therefore keeps an
+ * ARBITRARY host's row. Observed 2026-08-25: bd-aec.com's llms.txt described
+ * `/` with soqwriters.com's homepage copy and `/terms` with bd-charlotte.com's,
+ * and which sibling won changed every time a neighbour rebuilt, because the tie
+ * among same-path rows is broken by whatever order Postgres returns.
+ *
+ * Rules, per path, via `matchSitemapEntryRow`:
+ *  - this host's row wins outright
+ *  - an unattributed (NULL-site) row stands in when the host has none — legacy
+ *    rows from site-less syncs are genuinely ambiguous, and dropping them would
+ *    silently delete real pages from the one file AI crawlers read
+ *  - another host's row is never substituted; that path is simply not ours
+ *
+ * A site-less call is the legacy project-wide read: dedupe only, no filtering.
+ */
+export declare function scopeSeoPagesToSite<T extends SeoPageRowLike & {
+    path: string;
+}>(rows: T[], site: string | null | undefined, primaryHost: string | null | undefined): T[];
+/**
+ * Agent-native contract: JSON Schema for the minimal row shape, so services and
+ * agents can validate candidate rows before handing them to `pickSeoPageRow`.
+ */
+export declare const SEO_PAGE_ROW_JSON_SCHEMA: {
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+    readonly $id: 'https://sonor.io/schemas/seo-page-row.v1.json';
+    readonly title: 'SeoPageRowLike';
+    readonly description: 'The subset of an seo_pages row that determines per-site resolution.';
+    readonly type: 'object';
+    readonly properties: {
+        readonly site: {
+            readonly description: 'Normalized sub-site host, or null for a project-wide row.';
+            readonly type: readonly ['string', 'null'];
+        };
+        readonly updated_at: {
+            readonly description: 'ISO 8601 timestamp; ties in resolution break toward the most recent.';
+            readonly type: readonly ['string', 'null'];
+        };
+    };
+    readonly additionalProperties: true;
+};