@sonordev/contracts 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2.5.0
+
+A minor release: one new entry, `@sonordev/contracts/sentences`, and a cache tag for commerce. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/sentences`**: where prose splits into sentences, so every app that cuts an excerpt, a social slide or a summary out of an article ends sentences in the same places.
+  - `splitSentences(text)` returns the trimmed sentences of `text`. It's lossless: joining the result with spaces gives back every word of the input, in order. The usual one-liners aren't: `text.match(/[^.!?]+[.!?]+(?=\s|$)/g)` skips ahead at a period it can't use (the first one in "9 p.m.") and drops every word before its next match, and `text.match(/[^.!?]+[.!?]+/g)` cuts "9 p.m." into "9 p." and "m.".
+  - It doesn't end a sentence at a dotted abbreviation of letters ("p.m.", "U.S.", "e.g."), a single letter ("J."), a common short form (titles, company and street suffixes, months, and days of the week when capitalized: "Dr.", "Inc.", "Ave.", "Sept.", "Mon."), a label before a number ("No. 5", "Fig. 2") or a list number ("1.", "Step 2."), and never before a lowercase word. A piece with no letter in it ("...", "1.") joins the next sentence. A `!` or `?` right after an abbreviation still ends one.
+  - Prices, versions, domains and email addresses ("$4.50", "v2.1", "example.com") aren't abbreviations: a sentence can end after them.
+  - It runs in linear time: a megabyte of text takes milliseconds, however many abbreviations it holds.
+  - A newline or a list marker isn't a boundary by itself, so split on lines or paragraphs first when those matter.
+  - Empty, whitespace-only, `null` and `undefined` input give `[]`.
+- **`site-cache`**: `SITE_CACHE_TAGS.commerce` (`commerce`) is the tag for products, services, events and membership plans. commerce-kit tags its server fetches with it, and the Sonor API expires it when an offering changes. The other tags are unchanged.
+
+## 2.4.0
+
+A minor release: one new entry, `@sonordev/contracts/schema-placeholders`, and the llms.txt sanitizers stop cutting mid-word. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/schema-placeholders`**: whether stored JSON-LD carries a template's unfilled slots, so the API that serves it and the site that renders it drop the same nodes.
+  - `withoutSchemaPlaceholders(value)` returns `{ value, dropped, notes }`: the JSON-LD without its placeholder nodes (the same reference when nothing was found, `null` when nothing real is left), every node it removed with the reason and the evidence, and the AI note keys it stripped from nodes it kept.
+  - `findSchemaPlaceholders(value)` returns just the nodes, and `describeSchemaPlaceholder(node)` turns one into a line a person can act on.
+  - It finds reserved example domains (`example.com`, `example.net`, `example.org`, `.example`) in URLs, hosts and emails, whole-value template names ("Example", "Your Business Name"), placeholder phones, bracketed and JSX slots (`[Resident Name]`, `{plan.name}`, `{{business_name}}`), `REPLACE_WITH_` markers, and objects that are only a note. A URI template's `{search_term_string}`, a real name that contains "Example" and a 555 number outside the fiction range are left alone.
+- **`llms`**: `clipAtWordBoundary(text, max)` cuts prose to a length without splitting a word. It ends at a sentence when one closes in the last 40% of the window, otherwise at the last whole word with an ellipsis, and never returns more than `max` characters. `sanitizeLlmsPublicSummary` and `sanitizeLlmsDisclaimerLine` now cut with it, so a long summary ends at a sentence or a whole word instead of mid-word. The limits are unchanged (400 and 280).
+
 ## 2.3.0
 
 A minor release: one new entry, `@sonordev/contracts/error-page`. Every other entry is unchanged.

package/README.md

@@ -14,7 +14,7 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/sites` | The canonical shape of a site host (the multi-site `site` dimension) | every ingest and read that filters by site |
 | `@sonordev/contracts/seo-pages` | Which `seo_pages` row a path resolves to on a multi-site project | the Sonor API, Signal, site-kit's sitemap sync |
 | `@sonordev/contracts/seo-meta` | Whether a title or description is fit to ship | site-kit, Signal's SEO gate |
-| `@sonordev/contracts/llms` | llms.txt sanitizers and contract version | site-kit, the Sonor API, Signal's schema validation |
+| `@sonordev/contracts/llms` | llms.txt sanitizers, the word-safe cut they use (`clipAtWordBoundary`), and the contract version | site-kit, the Sonor API, Signal's schema validation |
 | `@sonordev/contracts/forms` | The honeypot policy | site-kit forms, the Sonor API's form intake |
 | `@sonordev/contracts/fleet` | The fleet heartbeat's wire shape | site-kit, the Sonor API |
 | `@sonordev/contracts/slots` | Slot payload signing, contract v2 (HMAC; Node only). Signs and verifies v1 for older site-kit releases | the Sonor API, site-kit on the server |
@@ -25,6 +25,42 @@ pnpm add @sonordev/contracts
 | `@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 |
 | `@sonordev/contracts/error-page` | Whether stored text is a rendered error page rather than a page's content, and whether generated copy says the page itself is missing | anything that stores page text or writes page copy from it: the Sonor API's page-view and sitemap writers, Signal's metadata generators |
+| `@sonordev/contracts/schema-placeholders` | Whether stored JSON-LD carries a template's unfilled slots (`example.com` URLs, an `Organization` named "Example", a placeholder phone, `[Resident Name]`, `{plan.name}`), and the value without them | site-kit's schema output, the Sonor API's schema reads and writes |
+| `@sonordev/contracts/sentences` | Where prose splits into sentences, without dropping a word or ending one at "p.m." (`splitSentences`) | anything that cuts an excerpt, a social slide or a summary out of an article: the Sonor API's carousels, Signal's article pipeline |
+
+## Schema placeholders
+
+`schema-placeholders` finds the parts of a JSON-LD value that a template left
+unfilled, so a site never publishes them as the business's identity. Schema
+extracted from a site's source, where the base URL was a variable, comes back
+as `https://example.com`; a template filled in by hand or by an AI can leave
+"Example", `+1-000-000-0000`, `[Resident Name]`, `{plan.name}`, or an object
+that's only a note about what goes there.
+
+```ts
+import { withoutSchemaPlaceholders, describeSchemaPlaceholder } from '@sonordev/contracts/schema-placeholders'
+
+const { value, dropped } = withoutSchemaPlaceholders(storedJsonLd)
+// value: the JSON-LD without its placeholder nodes (the same reference when
+// nothing was found, null when nothing real is left)
+dropped.map(describeSchemaPlaceholder)
+// ['Organization at $: name "Example" is a placeholder name']
+```
+
+- **The unit is the node.** The innermost object with an `@type` or `@id` (or
+  a top-level or `@graph` member) whose own values hold the placeholder is
+  dropped whole. Its real siblings, and a real parent it hangs off, stay. A
+  node left with nothing but JSON-LD keywords once its placeholder children are
+  gone goes too.
+- **Conservative on purpose.** A false positive removes real schema from a live
+  site, so names match whole values only ("Example Plumbing Co" is a real
+  name), domains are only the reserved example domains, phones are only
+  all-zero, sequential, `XXX` and the 555-0100 to 555-0199 fiction range, and a
+  URI template's `{search_term_string}` is how schema.org spells a
+  `SearchAction`, never a finding.
+- **Notes.** An AI's `note` key on a real node isn't schema.org vocabulary: it's
+  stripped and the node stays. An object that's only a note is dropped.
+- **Pure.** The input is never mutated.
 
 ## The voice contract
 
@@ -252,6 +288,68 @@ A text-only check can't prove a page failed. Where you observed the HTTP
 status, require 400 or more as well and use this as the fallback; the header of
 `src/contracts/error-page.ts` lists the other known limits.
 
+## The sentences contract
+
+Cutting an excerpt, a slide or a summary out of an article starts with
+finding where its sentences end, and the usual one-liners for that get it
+wrong. `text.match(/[^.!?]+[.!?]+(?=\s|$)/g)` can't end a match at the first
+period of "9 p.m.", so it skips ahead and drops every word before the next
+match: "We open at 9 p.m. daily." comes back as "m." and " daily.". Without
+the lookahead, `text.match(/[^.!?]+[.!?]+/g)` cuts "9 p.m." into "9 p." and
+"m.". Both also drop any text after the last full stop. `splitSentences` is
+the one splitter to use instead.
+
+- **Lossless.** Joining the result with spaces gives back every word of the
+  input, in order. Nothing is dropped, added or reordered, and each sentence
+  comes back trimmed and non-empty.
+- **Where a sentence ends.** At `.`, `!` or `?` (and any closing `"`, `'`, `”`,
+  `’`, `)` or `]` after it) followed by whitespace and then `A` to `Z` or `0`
+  to `9`, optionally after one opening `"`, `'`, `“`, `‘`, `(` or `[`. Never
+  before a lowercase word or a symbol. Only ASCII capitals count: a sentence
+  that opens with an accented, Greek or Cyrillic capital, a currency sign, `#`,
+  `@` or an emoji stays joined to the one before it.
+- **Where it doesn't.** After a dotted abbreviation made of letters ("p.m.",
+  "U.S.", "e.g.", "Ph.D."), a single letter of either case (an initial like
+  "J.", but also "Plan A."), or a short form on its list: titles, company
+  suffixes, months, street suffixes and days of the week ("Dr.", "Inc.",
+  "Sept.", "Ave.", "Mon."). A few of those only count when capitalized, because
+  the lowercase word ends sentences too ("Mon." is a day, "the sun." isn't).
+  A label with a number after it stays together ("No. 5", "Fig. 2",
+  "Ste. 200"), while "No." before anything else ends a sentence. A list number
+  ("1.", "Step 2.", "Do three things: 1.") stays with its item.
+- **`!` and `?`.** An abbreviation only holds back a period. "Open until 9
+  p.m.? Yes!" is two sentences, under the same start-of-sentence rule as above.
+- **Prices, versions and web addresses** ("$4.50", "v2.1", "example.com",
+  "info@example.com") aren't abbreviations: a sentence can end after them.
+- **Never a bare mark.** A piece with no letter in it ("...", "?!", "1.")
+  isn't a sentence. It joins the next one.
+- **Prose, not layout.** A newline or a list marker doesn't start a new
+  sentence by itself. If lines or paragraphs matter, split on those first and
+  call `splitSentences` on each one.
+- **Empty is `[]`.** Empty, whitespace-only, `null` and `undefined` input all
+  give an empty array, never `null`, so callers can iterate without a guard.
+- **Linear time.** One pass over the text. A megabyte takes milliseconds,
+  however many abbreviations, stops or quotes it holds.
+
+```ts
+import { splitSentences } from '@sonordev/contracts/sentences'
+
+splitSentences('We open at 9 a.m. daily. Walk-ins are welcome.')
+// ['We open at 9 a.m. daily.', 'Walk-ins are welcome.']
+
+splitSentences(excerptSource).slice(0, 2).join(' ')
+// the first two sentences, whole
+```
+
+Known limits. Where it can't be sure it leans toward joining, because a
+sentence that runs long costs less than a lost word, and a caller that caps
+length should cut at a word. It can't tell an abbreviation that ends a
+sentence from one that doesn't ("Contact Acme Inc. Our team ..." and "... in
+Washington, D.C. Residents ..." each stay in one piece), it only knows English
+short forms (a period after one it doesn't know ends a sentence, so "Sra.
+García" splits after "Sra."), and the next sentence has to start with `A` to
+`Z` or a digit.
+
 ## Why it exists
 
 A rule that lives in several copies is how two of them end up disagreeing.

package/dist/color.d.ts

@@ -4,7 +4,7 @@
  * Single source of truth for turning a CSS colour string into something the
  * kit can reason about. Used at build time by the brand-profile extractor
  * (`src/brand/extract-brand-profile.ts`, theme detection) and in the browser
- * by Echo (`src/engage/brand-color.ts`, brand text contrast). Pure, no
+ * by Echo (`src/chat/brand-color.ts`, brand text contrast). Pure, no
  * imports, safe in both.
  */
 export type Rgb = {

package/dist/llms.d.ts

@@ -28,6 +28,7 @@ export interface LLMsPayloadMeta {
     /** Optional single-line, public-safe note in the llms.txt blockquote (e.g. scope / not legal advice). */
     llms_disclaimer?: string | null;
 }
+export declare function clipAtWordBoundary(text: string, max: number): string;
 /**
  * Public-safe summary for llms.txt `[title](url): notes` — never CRM-only or internal copy.
  */

package/dist/llms.js

@@ -18,14 +18,64 @@ var MANAGED_LLM_SCHEMA_KNOWN_KEYS = /* @__PURE__ */ new Set([
   "speakable",
   "additionalType"
 ]);
+var SENTENCE_SHARE = 0.4;
+var ELLIPSIS = "\u2026";
+var CLOSERS = /* @__PURE__ */ new Set(['"', "'", ")", "]", "\u201D", "\u2019", "\xBB"]);
+var ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "mr",
+  "mrs",
+  "ms",
+  "dr",
+  "prof",
+  "st",
+  "mt",
+  "ft",
+  "jr",
+  "sr",
+  "inc",
+  "ltd",
+  "co",
+  "corp",
+  "vs",
+  "no"
+]);
+var TRAILING_SEPARATORS = /[\s.,;:\-\u2013\u2014/&([{]+$/;
+function clipAtWordBoundary(text, max) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  if (flat.length <= max) return flat;
+  if (max < 2) return flat.slice(0, Math.max(0, max));
+  const floor = Math.floor(max * (1 - SENTENCE_SHARE));
+  for (let end = max; end > floor; end--) {
+    if (endsSentence(flat, end)) return flat.slice(0, end);
+  }
+  const room = max - 1;
+  const space = flat.lastIndexOf(" ", room);
+  if (space <= 0) return `${flat.slice(0, room)}${ELLIPSIS}`;
+  if (endsSentence(flat, space)) return flat.slice(0, space);
+  const head = flat.slice(0, space).replace(TRAILING_SEPARATORS, "");
+  return `${head || flat.slice(0, room)}${ELLIPSIS}`;
+}
+function endsSentence(flat, end) {
+  if (flat[end] !== " ") return false;
+  let i = end - 1;
+  while (i > 0 && CLOSERS.has(flat[i])) i--;
+  const terminator = flat[i];
+  if (terminator === "!" || terminator === "?") return true;
+  return terminator === "." && !isAbbreviation(flat, i);
+}
+function isAbbreviation(flat, dot) {
+  let start = dot;
+  while (start > 0 && flat[start - 1] !== " ") start--;
+  const token = flat.slice(start, dot).replace(/^[("'[\u201c\u2018]+/, "").toLowerCase();
+  if (token.includes(".") || /^[a-z]$/.test(token)) return true;
+  return ABBREVIATIONS.has(token);
+}
 function sanitizeLlmsPublicSummary(raw) {
   if (raw === null || raw === void 0) return null;
   if (typeof raw !== "string") return null;
   let s = raw.trim().replace(/\s+/g, " ");
   s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
-  if (s.length > LLMS_PUBLIC_SUMMARY_MAX_LENGTH) {
-    s = `${s.slice(0, LLMS_PUBLIC_SUMMARY_MAX_LENGTH - 1).trimEnd()}\u2026`;
-  }
+  s = clipAtWordBoundary(s, LLMS_PUBLIC_SUMMARY_MAX_LENGTH);
   if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
   if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
   if (s.length < 8) return null;
@@ -36,9 +86,7 @@ function sanitizeLlmsDisclaimerLine(raw) {
   if (typeof raw !== "string") return null;
   let s = raw.trim().replace(/\s+/g, " ");
   s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
-  if (s.length > LLMS_DISCLAIMER_MAX_LENGTH) {
-    s = `${s.slice(0, LLMS_DISCLAIMER_MAX_LENGTH - 1).trimEnd()}\u2026`;
-  }
+  s = clipAtWordBoundary(s, LLMS_DISCLAIMER_MAX_LENGTH);
   if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
   if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
   if (s.length < 3) return null;
@@ -100,6 +148,7 @@ exports.LLMS_DISCLAIMER_MAX_LENGTH = LLMS_DISCLAIMER_MAX_LENGTH;
 exports.LLMS_PUBLIC_SUMMARY_MAX_LENGTH = LLMS_PUBLIC_SUMMARY_MAX_LENGTH;
 exports.LLM_GEO_CONTRACT_VERSION = LLM_GEO_CONTRACT_VERSION;
 exports.MANAGED_LLM_SCHEMA_KNOWN_KEYS = MANAGED_LLM_SCHEMA_KNOWN_KEYS;
+exports.clipAtWordBoundary = clipAtWordBoundary;
 exports.isEmittableReviewNode = isEmittableReviewNode;
 exports.pickManagedLlmSchemaForJsonLd = pickManagedLlmSchemaForJsonLd;
 exports.sanitizeLlmsDisclaimerLine = sanitizeLlmsDisclaimerLine;

package/dist/llms.mjs

@@ -16,14 +16,64 @@ var MANAGED_LLM_SCHEMA_KNOWN_KEYS = /* @__PURE__ */ new Set([
   "speakable",
   "additionalType"
 ]);
+var SENTENCE_SHARE = 0.4;
+var ELLIPSIS = "\u2026";
+var CLOSERS = /* @__PURE__ */ new Set(['"', "'", ")", "]", "\u201D", "\u2019", "\xBB"]);
+var ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "mr",
+  "mrs",
+  "ms",
+  "dr",
+  "prof",
+  "st",
+  "mt",
+  "ft",
+  "jr",
+  "sr",
+  "inc",
+  "ltd",
+  "co",
+  "corp",
+  "vs",
+  "no"
+]);
+var TRAILING_SEPARATORS = /[\s.,;:\-\u2013\u2014/&([{]+$/;
+function clipAtWordBoundary(text, max) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  if (flat.length <= max) return flat;
+  if (max < 2) return flat.slice(0, Math.max(0, max));
+  const floor = Math.floor(max * (1 - SENTENCE_SHARE));
+  for (let end = max; end > floor; end--) {
+    if (endsSentence(flat, end)) return flat.slice(0, end);
+  }
+  const room = max - 1;
+  const space = flat.lastIndexOf(" ", room);
+  if (space <= 0) return `${flat.slice(0, room)}${ELLIPSIS}`;
+  if (endsSentence(flat, space)) return flat.slice(0, space);
+  const head = flat.slice(0, space).replace(TRAILING_SEPARATORS, "");
+  return `${head || flat.slice(0, room)}${ELLIPSIS}`;
+}
+function endsSentence(flat, end) {
+  if (flat[end] !== " ") return false;
+  let i = end - 1;
+  while (i > 0 && CLOSERS.has(flat[i])) i--;
+  const terminator = flat[i];
+  if (terminator === "!" || terminator === "?") return true;
+  return terminator === "." && !isAbbreviation(flat, i);
+}
+function isAbbreviation(flat, dot) {
+  let start = dot;
+  while (start > 0 && flat[start - 1] !== " ") start--;
+  const token = flat.slice(start, dot).replace(/^[("'[\u201c\u2018]+/, "").toLowerCase();
+  if (token.includes(".") || /^[a-z]$/.test(token)) return true;
+  return ABBREVIATIONS.has(token);
+}
 function sanitizeLlmsPublicSummary(raw) {
   if (raw === null || raw === void 0) return null;
   if (typeof raw !== "string") return null;
   let s = raw.trim().replace(/\s+/g, " ");
   s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
-  if (s.length > LLMS_PUBLIC_SUMMARY_MAX_LENGTH) {
-    s = `${s.slice(0, LLMS_PUBLIC_SUMMARY_MAX_LENGTH - 1).trimEnd()}\u2026`;
-  }
+  s = clipAtWordBoundary(s, LLMS_PUBLIC_SUMMARY_MAX_LENGTH);
   if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
   if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
   if (s.length < 8) return null;
@@ -34,9 +84,7 @@ function sanitizeLlmsDisclaimerLine(raw) {
   if (typeof raw !== "string") return null;
   let s = raw.trim().replace(/\s+/g, " ");
   s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
-  if (s.length > LLMS_DISCLAIMER_MAX_LENGTH) {
-    s = `${s.slice(0, LLMS_DISCLAIMER_MAX_LENGTH - 1).trimEnd()}\u2026`;
-  }
+  s = clipAtWordBoundary(s, LLMS_DISCLAIMER_MAX_LENGTH);
   if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
   if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
   if (s.length < 3) return null;
@@ -94,4 +142,4 @@ function pickManagedLlmSchemaForJsonLd(schema) {
   return Object.keys(out).length ? out : null;
 }
 
-export { LLMS_DISCLAIMER_MAX_LENGTH, LLMS_PUBLIC_SUMMARY_MAX_LENGTH, LLM_GEO_CONTRACT_VERSION, MANAGED_LLM_SCHEMA_KNOWN_KEYS, isEmittableReviewNode, pickManagedLlmSchemaForJsonLd, sanitizeLlmsDisclaimerLine, sanitizeLlmsPublicSummary, sanitizePrimaryLanguageTag };
+export { LLMS_DISCLAIMER_MAX_LENGTH, LLMS_PUBLIC_SUMMARY_MAX_LENGTH, LLM_GEO_CONTRACT_VERSION, MANAGED_LLM_SCHEMA_KNOWN_KEYS, clipAtWordBoundary, isEmittableReviewNode, pickManagedLlmSchemaForJsonLd, sanitizeLlmsDisclaimerLine, sanitizeLlmsPublicSummary, sanitizePrimaryLanguageTag };

package/dist/schema-placeholders.d.ts

@@ -0,0 +1,87 @@
+/**
+ * JSON-LD template placeholders: found once, dropped wherever sonor-api serves
+ * stored schema to a site, and never stored as implemented by register-schema.
+ *
+ * Stored JSON-LD (seo_schema_markup.schema_json, seo_pages.managed_schema) can
+ * carry a template's unfilled slots. Schema extracted from a site's source,
+ * where the base URL was a variable, comes back as https://example.com; an AI
+ * filling a template leaves "Example", "+1-000-000-0000", "[Resident Name]",
+ * "{plan.name}", or an object that is only a "note" saying what goes there.
+ * site-kit renders all of it on the live page, where search engines and AI
+ * crawlers take it as the business's identity. Observed 2026-10-01: a live
+ * site served an Organization named "Example", phone +1-000-000-0000, on its
+ * home page, and dozens more of its implemented rows carried example.com URLs
+ * and unfilled template slots.
+ *
+ * Conservative on purpose, because a false positive removes real schema from a
+ * live site:
+ *   - Domains: only the reserved example domains (example.com, example.net,
+ *     example.org, their subdomains, and the .example TLD), and only when the
+ *     whole value is a URL, host or email address. A real domain with
+ *     "example" in its path, or prose that mentions example.com, is fine.
+ *   - Names: whole-value matches only (trimmed, case-insensitive) on name-like
+ *     properties. "Example Plumbing Co" is a real name.
+ *   - Phones (telephone, faxNumber, tel: links): all zeros, 123-456-7890,
+ *     XXX-XXX-XXXX, and 555-0100 through 555-0199, the North American range
+ *     reserved for fiction. 555-0200 and 555-1212 are real numbers.
+ *   - Template slots: a value that is wholly a bracketed slot ("[YYYY-MM-DD]")
+ *     or a JSX expression ("{plan.name}"), a {{mustache}} slot, a
+ *     REPLACE_WITH_ marker, a title-case field name in brackets inside text
+ *     ("Call [Phone Number]"), or a JSX member expression inside a URL. A URI
+ *     template's {search_term_string} is how schema.org spells a SearchAction
+ *     and is never a finding.
+ *   - Annotations: an object that holds nothing but an AI note. A note key on
+ *     a real node is stripped (it isn't schema.org vocabulary) and the node
+ *     stays.
+ *
+ * The unit is the NODE: the innermost object with @type or @id (or a top-level
+ * or @graph member) whose own values hold the placeholder. A placeholder node
+ * is dropped whole, since its other values came from the same unfilled
+ * template. Its real siblings, and a real parent it hangs off, stay: an
+ * FAQPage keeps its questions when only its publisher was a placeholder. A
+ * node left with nothing but JSON-LD keywords once its placeholder children
+ * are gone (a BreadcrumbList whose every item was a placeholder) goes too, so
+ * the site falls back to what it generates itself.
+ *
+ * Single source of truth for "is this stored schema a placeholder", published
+ * as `@sonordev/contracts/schema-placeholders`: sonor-api's public schema reads
+ * and register-schema, and site-kit's ManagedSchema and LLMSchema (so a site
+ * drops a placeholder whichever Sonor source served it) all call it. Add new
+ * shapes here, with a test, never in a caller.
+ */
+export type SchemaPlaceholderReason = 'example_domain' | 'placeholder_phone' | 'placeholder_name' | 'template_token' | 'annotation' | 'emptied';
+export interface SchemaPlaceholderEvidence {
+    reason: SchemaPlaceholderReason;
+    /** The property that held the value. */
+    key: string;
+    /** The value, cut short for logs. */
+    value: string;
+}
+export interface SchemaPlaceholderNode {
+    /** Where the node sits: '$' for the root, then .key and [index] steps. */
+    path: string;
+    /** The node's @type ('A,B' when it has several), or null. */
+    type: string | null;
+    reasons: SchemaPlaceholderReason[];
+    evidence: SchemaPlaceholderEvidence[];
+}
+export interface SchemaPlaceholderScan<T> {
+    /** The value without its placeholder nodes: the same reference when nothing was found, null when nothing real is left. */
+    value: T | null;
+    /** Every node removed, outermost only (a dropped node's children go with it). */
+    dropped: SchemaPlaceholderNode[];
+    /** AI note keys stripped from nodes that were kept. */
+    notes: Array<{
+        path: string;
+        key: string;
+    }>;
+}
+/**
+ * The value with its placeholder nodes removed, and what was removed. Pure; the
+ * input is never mutated.
+ */
+export declare function withoutSchemaPlaceholders<T>(value: T): SchemaPlaceholderScan<T>;
+/** Which nodes of a JSON-LD value are placeholders, and why. */
+export declare function findSchemaPlaceholders(value: unknown): SchemaPlaceholderNode[];
+/** One line a person can act on: 'Organization at $: name "Example" is a placeholder name'. */
+export declare function describeSchemaPlaceholder(node: SchemaPlaceholderNode): string;