@sonordev/contracts 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2.6.0
+
+A minor release: one new entry, `@sonordev/contracts/knowledge`. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/knowledge`**: which Sonor records Signal reads into a project's knowledge, where each one's knowledge is stored, and how big a page sync may be, so the API that announces a change and Signal, which indexes it, agree.
+  - `KNOWLEDGE_RECORD_KINDS` lists the record kinds (`portfolio`, `proof`, `faq`, `review`, `article`, `offering`), and `isKnowledgeRecordKind(value)` checks one.
+  - `knowledgeRecordSourceUrl(kind, id, anchor?)` builds a record's address (`faq://<id>`, `article://<id>#pricing`) and `knowledgeRecordPrefix(kind)` the `<kind>://` all of a kind's addresses start with.
+  - `knowledgeRecordKindOf(url)` tells a record's row from a page passage by its scheme, and `knowledgeRecordRefOf(url)` returns the `{ kind, id }` an address names, the legacy `commerce://offering/<id>` (`legacyOfferingSourceUrl`) included.
+  - `KNOWLEDGE_SYNC_MAX_PAGES` (500), `KNOWLEDGE_SYNC_PATH_MAX_LENGTH` (2048) and `KNOWLEDGE_SYNC_SITE_MAX_LENGTH` (253) are the limits of one page sync, and `KnowledgePageChange` is the shape of each page in it. Signal applies every removal in a call and reads the changed pages in the order given, so a sender puts removals first.
+
+## 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.

package/README.md

@@ -26,6 +26,8 @@ pnpm add @sonordev/contracts
 | `@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 |
+| `@sonordev/contracts/knowledge` | Which Sonor records Signal reads into a project's knowledge, the address each one's knowledge is stored under (`portfolio://<id>`), and the limits of the call that tells Signal a site's pages changed | the Sonor API sends those calls and Signal answers them |
 
 ## Schema placeholders
 
@@ -287,6 +289,131 @@ 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.
+
+## The knowledge contract
+
+Signal answers questions about a business from what it has read: the
+passages of the site's live pages, and the business's own records in Sonor.
+The Sonor API tells Signal when either changes, and Signal indexes it. Both
+have to agree on which records count, how a stored row says which record it
+came from, and how big a page sync may be. If they don't, a record the API
+announces is refused, or a row Signal wrote reads as a page. Anything that
+shows what Signal has read, like the dashboard's view of it, reads stored
+addresses by the same rules.
+
+- **Record kinds.** `KNOWLEDGE_RECORD_KINDS` is `portfolio` (case studies),
+  `proof` (proof records), `faq` (managed FAQs), `review`, `article` and
+  `offering` (commerce offerings), in the order the dashboard lists them.
+  `isKnowledgeRecordKind(value)` is true only for one of them, spelled exactly.
+- **Addresses.** A record's knowledge is stored under `<kind>://<id>`, and
+  any further chunk under `<kind>://<id>#<anchor>` (an article indexed in full
+  is split by heading). `knowledgeRecordSourceUrl(kind, id, anchor?)` builds
+  one and `knowledgeRecordPrefix(kind)` gives the `<kind>://` every address of
+  that kind starts with. The id is the record's UUID, and the caller checks
+  it: one holding `#`, `?`, `/` or whitespace can't be read back. A page's
+  passages are stored under the page's https URL instead, so the scheme alone
+  tells a record's rows apart. The content type can't: an article's record
+  has the same type as the page passages beside it, because a live article is
+  a page on the site.
+- **Reading an address.** `knowledgeRecordKindOf(url)` is the kind by scheme
+  alone, or `null` for a page passage, an older page summary or a note. It's
+  the test for whether a row belongs to a record. `knowledgeRecordRefOf(url)`
+  is `{ kind, id }` for the record an address names, or `null` when it names
+  none; the id runs to the first `#`, `?`, `/` or whitespace. Both ignore the
+  scheme's case and surrounding whitespace.
+- **The legacy offering address.** Offerings were once stored under
+  `commerce://offering/<id>` (`legacyOfferingSourceUrl(id)`). Nothing writes
+  it now, and Signal switches each such row off the next time its offering
+  syncs. Until then `knowledgeRecordRefOf` names the offering, while
+  `knowledgeRecordKindOf` doesn't count the row as a record's.
+- **A page sync.** One call names at most `KNOWLEDGE_SYNC_MAX_PAGES` (500)
+  pages, each a `KnowledgePageChange` (`{ site?, path, removed? }`) with a
+  path of at most `KNOWLEDGE_SYNC_PATH_MAX_LENGTH` (2048) characters and a
+  host of at most `KNOWLEDGE_SYNC_SITE_MAX_LENGTH` (253). Signal refuses a
+  longer list, path or host outright, so a sender keeps within them before it
+  calls. Signal applies every removal in the call, then reads the changed
+  pages in the order given, as many as it reads in one call; the rest wait for
+  its nightly sweep. So put removals first, then the pages that matter most,
+  and cut the list after ordering it.
+
+```ts
+import {
+  KNOWLEDGE_SYNC_MAX_PAGES,
+  knowledgeRecordRefOf,
+  knowledgeRecordSourceUrl,
+} from '@sonordev/contracts/knowledge'
+
+knowledgeRecordSourceUrl('faq', id)
+// 'faq://<id>'
+
+knowledgeRecordRefOf('article://<id>#part-2')
+// { kind: 'article', id: '<id>' }
+
+const batch = [...removed, ...changed].slice(0, KNOWLEDGE_SYNC_MAX_PAGES)
+// removals first, so the cut drops changed pages before any removal
+```
+
 ## Why it exists
 
 A rule that lives in several copies is how two of them end up disagreeing.

package/dist/knowledge.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Knowledge contract: which Sonor records Signal reads into a project's
+ * knowledge, the address each record's knowledge is stored under, and the
+ * limits of the call that tells Signal a site's pages changed. The Sonor API
+ * makes those calls and Signal answers them, so both import this as
+ * `@sonordev/contracts/knowledge` instead of keeping lists that drift apart.
+ * The dashboard, which shows the owner what Signal read, reads stored
+ * addresses by the same rules.
+ *
+ * A record's knowledge is stored under a URI built from its kind and id:
+ * `<kind>://<id>` for its first chunk and `<kind>://<id>#<anchor>` for any
+ * more (an article indexed in full, split by heading). The scheme is what
+ * tells a record's rows apart from a page's passages, which are stored under
+ * the page's https URL. The content type can't: an article's record has the
+ * same content type as the page passages beside it, because a live article is
+ * a page on the site.
+ */
+/**
+ * The kinds of Sonor record Signal indexes, in the order the dashboard lists
+ * them: case studies, proof records, managed FAQs, reviews, articles and
+ * commerce offerings. Each kind is also its URI scheme.
+ */
+export declare const KNOWLEDGE_RECORD_KINDS: readonly ["portfolio", "proof", "faq", "review", "article", "offering"];
+export type KnowledgeRecordKind = (typeof KNOWLEDGE_RECORD_KINDS)[number];
+/** True for one of KNOWLEDGE_RECORD_KINDS, spelled exactly (lowercase). */
+export declare function isKnowledgeRecordKind(value: unknown): value is KnowledgeRecordKind;
+/** `<kind>://`, the start every address of that kind shares, for prefix queries. */
+export declare function knowledgeRecordPrefix(kind: KnowledgeRecordKind): string;
+/**
+ * Where a record's knowledge is stored: `<kind>://<id>` for its first chunk,
+ * `<kind>://<id>#<anchor>` for a further one. `id` is the record's UUID, and
+ * checking it is the caller's job: an empty id, or one holding `#`, `?`, `/`
+ * or whitespace, builds an address knowledgeRecordRefOf can't read back.
+ */
+export declare function knowledgeRecordSourceUrl(kind: KnowledgeRecordKind, id: string, anchor?: string | null): string;
+/**
+ * The address an offering had before offerings were records of their own:
+ * `commerce://offering/<id>`. Nothing writes it any more. Signal switches the
+ * row off the next time that offering syncs, and a reader counts it as the
+ * offering until then (knowledgeRecordRefOf).
+ */
+export declare function legacyOfferingSourceUrl(id: string): string;
+/**
+ * The kind of record a stored address belongs to, by its scheme
+ * (`article://<id>#part-2` is 'article'), or null for anything else: a page
+ * passage, an older page summary, a note. Case doesn't matter and surrounding
+ * whitespace is ignored. This is the test for "is this row a record's": it
+ * reads only the scheme, so it doesn't need an id, and an offering's legacy
+ * address isn't a record row by it.
+ */
+export declare function knowledgeRecordKindOf(sourceUrl: string | null | undefined): KnowledgeRecordKind | null;
+/** The record a stored address names. */
+export interface KnowledgeRecordRef {
+    kind: KnowledgeRecordKind;
+    id: string;
+}
+/**
+ * The record a stored address names (`portfolio://<id>#part-2` is
+ * `{ kind: 'portfolio', id }`), or null when it names none. An offering's
+ * legacy address (`commerce://offering/<id>`) names that offering. Case
+ * doesn't matter in the scheme, surrounding whitespace is ignored, and the id
+ * keeps its own case.
+ */
+export declare function knowledgeRecordRefOf(sourceUrl: string | null | undefined): KnowledgeRecordRef | null;
+/**
+ * One page of a site in a page sync: it changed (Signal reads it live) or
+ * left the site (`removed`: Signal switches its passages off). Signal applies
+ * every removal in a call, then reads the changed pages in the order given,
+ * as many as it reads in one call; the rest wait for its nightly sweep. So a
+ * sender puts removals first, then the pages that matter most.
+ */
+export interface KnowledgePageChange {
+    /** The host as the project's pages store it; null or absent is the project's primary domain. */
+    site?: string | null;
+    /** The page's path, from "/". */
+    path: string;
+    removed?: boolean;
+}
+/** The most pages one page sync may name. Signal refuses a longer list outright, so cut the list after ordering it. */
+export declare const KNOWLEDGE_SYNC_MAX_PAGES = 500;
+/** The longest path a page sync may name, in characters. */
+export declare const KNOWLEDGE_SYNC_PATH_MAX_LENGTH = 2048;
+/** The longest host a page sync may name, in characters (a DNS name's limit). */
+export declare const KNOWLEDGE_SYNC_SITE_MAX_LENGTH = 253;

package/dist/knowledge.js

@@ -0,0 +1,48 @@
+'use strict';
+
+// src/contracts/knowledge.ts
+var KNOWLEDGE_RECORD_KINDS = Object.freeze(["portfolio", "proof", "faq", "review", "article", "offering"]);
+function isKnowledgeRecordKind(value) {
+  return typeof value === "string" && KNOWLEDGE_RECORD_KINDS.includes(value);
+}
+function knowledgeRecordPrefix(kind) {
+  return `${kind}://`;
+}
+function knowledgeRecordSourceUrl(kind, id, anchor) {
+  const base = `${knowledgeRecordPrefix(kind)}${id}`;
+  return anchor ? `${base}#${anchor}` : base;
+}
+function legacyOfferingSourceUrl(id) {
+  return `${LEGACY_OFFERING_PREFIX}${id}`;
+}
+var LEGACY_OFFERING_PREFIX = "commerce://offering/";
+var RECORD_SCHEME = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://`, "i");
+var RECORD_REF = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://([^#?/\\s]+)`, "i");
+var LEGACY_OFFERING_REF = /^commerce:\/\/offering\/([^#?/\s]+)/i;
+function knowledgeRecordKindOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const match = RECORD_SCHEME.exec(sourceUrl.trim());
+  return match ? match[1].toLowerCase() : null;
+}
+function knowledgeRecordRefOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const value = sourceUrl.trim();
+  const record = RECORD_REF.exec(value);
+  if (record) return { kind: record[1].toLowerCase(), id: record[2] };
+  const legacy = LEGACY_OFFERING_REF.exec(value);
+  return legacy ? { kind: "offering", id: legacy[1] } : null;
+}
+var KNOWLEDGE_SYNC_MAX_PAGES = 500;
+var KNOWLEDGE_SYNC_PATH_MAX_LENGTH = 2048;
+var KNOWLEDGE_SYNC_SITE_MAX_LENGTH = 253;
+
+exports.KNOWLEDGE_RECORD_KINDS = KNOWLEDGE_RECORD_KINDS;
+exports.KNOWLEDGE_SYNC_MAX_PAGES = KNOWLEDGE_SYNC_MAX_PAGES;
+exports.KNOWLEDGE_SYNC_PATH_MAX_LENGTH = KNOWLEDGE_SYNC_PATH_MAX_LENGTH;
+exports.KNOWLEDGE_SYNC_SITE_MAX_LENGTH = KNOWLEDGE_SYNC_SITE_MAX_LENGTH;
+exports.isKnowledgeRecordKind = isKnowledgeRecordKind;
+exports.knowledgeRecordKindOf = knowledgeRecordKindOf;
+exports.knowledgeRecordPrefix = knowledgeRecordPrefix;
+exports.knowledgeRecordRefOf = knowledgeRecordRefOf;
+exports.knowledgeRecordSourceUrl = knowledgeRecordSourceUrl;
+exports.legacyOfferingSourceUrl = legacyOfferingSourceUrl;

package/dist/knowledge.mjs

@@ -0,0 +1,37 @@
+// src/contracts/knowledge.ts
+var KNOWLEDGE_RECORD_KINDS = Object.freeze(["portfolio", "proof", "faq", "review", "article", "offering"]);
+function isKnowledgeRecordKind(value) {
+  return typeof value === "string" && KNOWLEDGE_RECORD_KINDS.includes(value);
+}
+function knowledgeRecordPrefix(kind) {
+  return `${kind}://`;
+}
+function knowledgeRecordSourceUrl(kind, id, anchor) {
+  const base = `${knowledgeRecordPrefix(kind)}${id}`;
+  return anchor ? `${base}#${anchor}` : base;
+}
+function legacyOfferingSourceUrl(id) {
+  return `${LEGACY_OFFERING_PREFIX}${id}`;
+}
+var LEGACY_OFFERING_PREFIX = "commerce://offering/";
+var RECORD_SCHEME = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://`, "i");
+var RECORD_REF = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://([^#?/\\s]+)`, "i");
+var LEGACY_OFFERING_REF = /^commerce:\/\/offering\/([^#?/\s]+)/i;
+function knowledgeRecordKindOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const match = RECORD_SCHEME.exec(sourceUrl.trim());
+  return match ? match[1].toLowerCase() : null;
+}
+function knowledgeRecordRefOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const value = sourceUrl.trim();
+  const record = RECORD_REF.exec(value);
+  if (record) return { kind: record[1].toLowerCase(), id: record[2] };
+  const legacy = LEGACY_OFFERING_REF.exec(value);
+  return legacy ? { kind: "offering", id: legacy[1] } : null;
+}
+var KNOWLEDGE_SYNC_MAX_PAGES = 500;
+var KNOWLEDGE_SYNC_PATH_MAX_LENGTH = 2048;
+var KNOWLEDGE_SYNC_SITE_MAX_LENGTH = 253;
+
+export { KNOWLEDGE_RECORD_KINDS, KNOWLEDGE_SYNC_MAX_PAGES, KNOWLEDGE_SYNC_PATH_MAX_LENGTH, KNOWLEDGE_SYNC_SITE_MAX_LENGTH, isKnowledgeRecordKind, knowledgeRecordKindOf, knowledgeRecordPrefix, knowledgeRecordRefOf, knowledgeRecordSourceUrl, legacyOfferingSourceUrl };

package/dist/sentences.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Sentences contract: how prose is split into sentences, so the APIs that cut
+ * an excerpt, a carousel slide or a summary out of an article agree on where
+ * a sentence ends. The APIs import it as `@sonordev/contracts/sentences`.
+ *
+ * Lossless: joining the result with spaces gives back every word of the input,
+ * in order. The usual one-liner, `text.match(/[^.!?]+[.!?]+(?=\s|$)/g)`, isn't.
+ * A period it can't use, like the first one in "9 p.m. call", makes match()
+ * skip ahead and silently drop every word before its next match, so a
+ * sentence about a 9 p.m. call comes back as "m.". Don't re-fork a regex for
+ * this.
+ *
+ * A sentence ends at . ! or ? (and any closing quote or bracket after it)
+ * followed by whitespace, then an optional opening quote or bracket, then
+ * A to Z or 0 to 9. Never before a lowercase word or a symbol, and only ASCII
+ * capitals count. It doesn't end at:
+ *  - an abbreviation: a dotted one made of letters ("p.m.", "U.S.", "e.g.",
+ *    "Ph.D."), a single letter ("J.", "Plan A."), or a short form listed below
+ *    (titles, months, days, company suffixes, street suffixes);
+ *  - a label that has a number after it ("No. 5", "Fig. 2", "Ste. 200");
+ *  - a list number ("1.", "Step 2.", "Do three things: 1.").
+ * A piece with no letter in it ("...", "1.") isn't a sentence and joins the
+ * next one. A "!" or "?" is never held back by an abbreviation (only a period
+ * is), though the same start-of-sentence rule applies after it.
+ *
+ * Prices, versions, domains and email addresses ("$4.50", "v2.1",
+ * "example.com") are not abbreviations: a sentence can end after them.
+ *
+ * Where it is unsure it leans toward not splitting, because a sentence that
+ * runs long costs less than a lost word. A period after a short form that
+ * isn't listed ends a sentence like any other.
+ *
+ * It reads sentences, not layout. A newline or a list marker doesn't start a
+ * new sentence by itself, so split text into lines or paragraphs first when
+ * those matter, then split each one.
+ */
+/**
+ * Splits prose into trimmed sentences without dropping or reordering a word.
+ * Empty, blank and nullish input give `[]`, never `null`.
+ *
+ * One pass, linear in the length of the text: each run of . ! ? (and the
+ * closing quotes or brackets after it) is looked at once, an abbreviation or
+ * list-marker check reads only the last few characters, and the check for a
+ * letter reads each character once.
+ */
+export declare function splitSentences(text: string | null | undefined): string[];

package/dist/sentences.js

@@ -0,0 +1,179 @@
+'use strict';
+
+// src/contracts/sentences.ts
+var ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "mr",
+  "mrs",
+  "ms",
+  "dr",
+  "prof",
+  "st",
+  "jr",
+  "sr",
+  "vs",
+  "inc",
+  "co",
+  "corp",
+  "ltd",
+  "llc",
+  "approx",
+  "dept",
+  "jan",
+  "feb",
+  "mar",
+  "apr",
+  "jun",
+  "jul",
+  "aug",
+  "sep",
+  "sept",
+  "oct",
+  "nov",
+  "dec",
+  "gen",
+  "sen",
+  "gov",
+  "lt",
+  "col",
+  "capt",
+  "sgt",
+  "cpl",
+  "maj",
+  "adm",
+  "pres",
+  "atty",
+  "bros",
+  "mfg",
+  "assoc",
+  "univ",
+  "bldg",
+  "ste",
+  "ave",
+  "blvd",
+  "rd",
+  "ln",
+  "hwy",
+  "pkwy",
+  "pl"
+]);
+var CAPITALISED_ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "Mon",
+  "Tue",
+  "Tues",
+  "Wed",
+  "Thu",
+  "Thur",
+  "Thurs",
+  "Fri",
+  "Sat",
+  "Sun",
+  "Mt",
+  "Ft",
+  "Ct",
+  "Rep",
+  "Rev",
+  "Hon"
+]);
+var BEFORE_NUMBER = /* @__PURE__ */ new Set([
+  "no",
+  "nos",
+  "fig",
+  "figs",
+  "vol",
+  "vols",
+  "ch",
+  "sec",
+  "pp",
+  "cf",
+  "ca",
+  "est",
+  "ext",
+  "tel",
+  "ph",
+  "ste",
+  "apt",
+  "bldg",
+  "rm",
+  "hwy",
+  "rt",
+  "rte"
+]);
+var DOTTED_SHORT = /^\d*(?:[A-Za-z]{1,2}\.)+[A-Za-z]{1,2}$/;
+var DOTTED_CAPS = /^(?:[A-Z][A-Za-z]*\.)+[A-Z][A-Za-z]*$/;
+var ABBREVIATION_RANGE = /[A-Za-z]\.[-–—/]/;
+var LIST_MARKER_ALONE = /^\s*(?:(?:step|tip|reason|rule|point|item|option)\s+)?\d{1,3}\.$/i;
+var LIST_MARKER_AFTER_COLON = /:\s+\d{1,3}\.$/;
+var LIST_MARKER_REACH = 24;
+var OPENERS = /* @__PURE__ */ new Set(['"', "'", "\u201C", "\u2018", "(", "["]);
+var CLOSERS = /* @__PURE__ */ new Set(['"', "'", "\u201D", "\u2019", ")", "]"]);
+var SPACE = /\s/;
+var LETTER = /\p{L}/u;
+var DIGIT = /[0-9]/;
+var SENTENCE_START = /[A-Z0-9]/;
+var isStop = (c) => c === "." || c === "!" || c === "?";
+var isSpace = (c) => SPACE.test(c);
+function startsSentence(source, at) {
+  const c = OPENERS.has(source[at]) ? source[at + 1] : source[at];
+  return c !== void 0 && SENTENCE_START.test(c);
+}
+function digitFollows(source, at) {
+  const c = OPENERS.has(source[at]) ? source[at + 1] : source[at];
+  return c !== void 0 && DIGIT.test(c);
+}
+function isDottedAbbreviation(bare) {
+  const compound = Math.max(bare.lastIndexOf("-"), bare.lastIndexOf("\u2013"), bare.lastIndexOf("\u2014"), bare.lastIndexOf("/"));
+  const last = bare.slice(compound + 1);
+  return DOTTED_SHORT.test(last) || DOTTED_CAPS.test(last) || ABBREVIATION_RANGE.test(bare);
+}
+function endsWithAbbreviation(source, end, digitNext) {
+  let from = end;
+  while (from > 0 && !isSpace(source[from - 1])) from--;
+  let to = end;
+  while (from < to && OPENERS.has(source[from])) from++;
+  while (to > from && CLOSERS.has(source[to - 1])) to--;
+  while (to > from && source[to - 1] === ".") to--;
+  const bare = source.slice(from, to);
+  const lower = bare.toLowerCase();
+  return isDottedAbbreviation(bare) || /^[A-Za-z]$/.test(bare) || ABBREVIATIONS.has(lower) || CAPITALISED_ABBREVIATIONS.has(bare) || digitNext && BEFORE_NUMBER.has(lower);
+}
+function endsWithListMarker(source, start, end) {
+  const from = Math.max(start, end - LIST_MARKER_REACH);
+  const tail = source.slice(from, end);
+  return from === start && LIST_MARKER_ALONE.test(tail) || LIST_MARKER_AFTER_COLON.test(tail);
+}
+function splitSentences(text) {
+  const source = (text ?? "").trim();
+  if (!source) return [];
+  const sentences = [];
+  let start = 0;
+  let scanned = 0;
+  let sawLetter = false;
+  let i = 0;
+  while (i < source.length) {
+    if (!isStop(source[i])) {
+      i++;
+      continue;
+    }
+    let endsStrong = false;
+    while (i < source.length && isStop(source[i])) {
+      if (source[i] !== ".") endsStrong = true;
+      i++;
+    }
+    while (i < source.length && CLOSERS.has(source[i])) i++;
+    let next = i;
+    while (next < source.length && isSpace(source[next])) next++;
+    if (next === i || !startsSentence(source, next)) continue;
+    if (!sawLetter) sawLetter = LETTER.test(source.slice(scanned, i));
+    scanned = i;
+    if (!sawLetter) continue;
+    if (!endsStrong && (endsWithAbbreviation(source, i, digitFollows(source, next)) || endsWithListMarker(source, start, i))) continue;
+    sentences.push(source.slice(start, i).trim());
+    start = i;
+    sawLetter = false;
+  }
+  const rest = source.slice(start).trim();
+  if (rest) sentences.push(rest);
+  return sentences;
+}
+
+exports.splitSentences = splitSentences;

package/dist/sentences.mjs

@@ -0,0 +1,177 @@
+// src/contracts/sentences.ts
+var ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "mr",
+  "mrs",
+  "ms",
+  "dr",
+  "prof",
+  "st",
+  "jr",
+  "sr",
+  "vs",
+  "inc",
+  "co",
+  "corp",
+  "ltd",
+  "llc",
+  "approx",
+  "dept",
+  "jan",
+  "feb",
+  "mar",
+  "apr",
+  "jun",
+  "jul",
+  "aug",
+  "sep",
+  "sept",
+  "oct",
+  "nov",
+  "dec",
+  "gen",
+  "sen",
+  "gov",
+  "lt",
+  "col",
+  "capt",
+  "sgt",
+  "cpl",
+  "maj",
+  "adm",
+  "pres",
+  "atty",
+  "bros",
+  "mfg",
+  "assoc",
+  "univ",
+  "bldg",
+  "ste",
+  "ave",
+  "blvd",
+  "rd",
+  "ln",
+  "hwy",
+  "pkwy",
+  "pl"
+]);
+var CAPITALISED_ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "Mon",
+  "Tue",
+  "Tues",
+  "Wed",
+  "Thu",
+  "Thur",
+  "Thurs",
+  "Fri",
+  "Sat",
+  "Sun",
+  "Mt",
+  "Ft",
+  "Ct",
+  "Rep",
+  "Rev",
+  "Hon"
+]);
+var BEFORE_NUMBER = /* @__PURE__ */ new Set([
+  "no",
+  "nos",
+  "fig",
+  "figs",
+  "vol",
+  "vols",
+  "ch",
+  "sec",
+  "pp",
+  "cf",
+  "ca",
+  "est",
+  "ext",
+  "tel",
+  "ph",
+  "ste",
+  "apt",
+  "bldg",
+  "rm",
+  "hwy",
+  "rt",
+  "rte"
+]);
+var DOTTED_SHORT = /^\d*(?:[A-Za-z]{1,2}\.)+[A-Za-z]{1,2}$/;
+var DOTTED_CAPS = /^(?:[A-Z][A-Za-z]*\.)+[A-Z][A-Za-z]*$/;
+var ABBREVIATION_RANGE = /[A-Za-z]\.[-–—/]/;
+var LIST_MARKER_ALONE = /^\s*(?:(?:step|tip|reason|rule|point|item|option)\s+)?\d{1,3}\.$/i;
+var LIST_MARKER_AFTER_COLON = /:\s+\d{1,3}\.$/;
+var LIST_MARKER_REACH = 24;
+var OPENERS = /* @__PURE__ */ new Set(['"', "'", "\u201C", "\u2018", "(", "["]);
+var CLOSERS = /* @__PURE__ */ new Set(['"', "'", "\u201D", "\u2019", ")", "]"]);
+var SPACE = /\s/;
+var LETTER = /\p{L}/u;
+var DIGIT = /[0-9]/;
+var SENTENCE_START = /[A-Z0-9]/;
+var isStop = (c) => c === "." || c === "!" || c === "?";
+var isSpace = (c) => SPACE.test(c);
+function startsSentence(source, at) {
+  const c = OPENERS.has(source[at]) ? source[at + 1] : source[at];
+  return c !== void 0 && SENTENCE_START.test(c);
+}
+function digitFollows(source, at) {
+  const c = OPENERS.has(source[at]) ? source[at + 1] : source[at];
+  return c !== void 0 && DIGIT.test(c);
+}
+function isDottedAbbreviation(bare) {
+  const compound = Math.max(bare.lastIndexOf("-"), bare.lastIndexOf("\u2013"), bare.lastIndexOf("\u2014"), bare.lastIndexOf("/"));
+  const last = bare.slice(compound + 1);
+  return DOTTED_SHORT.test(last) || DOTTED_CAPS.test(last) || ABBREVIATION_RANGE.test(bare);
+}
+function endsWithAbbreviation(source, end, digitNext) {
+  let from = end;
+  while (from > 0 && !isSpace(source[from - 1])) from--;
+  let to = end;
+  while (from < to && OPENERS.has(source[from])) from++;
+  while (to > from && CLOSERS.has(source[to - 1])) to--;
+  while (to > from && source[to - 1] === ".") to--;
+  const bare = source.slice(from, to);
+  const lower = bare.toLowerCase();
+  return isDottedAbbreviation(bare) || /^[A-Za-z]$/.test(bare) || ABBREVIATIONS.has(lower) || CAPITALISED_ABBREVIATIONS.has(bare) || digitNext && BEFORE_NUMBER.has(lower);
+}
+function endsWithListMarker(source, start, end) {
+  const from = Math.max(start, end - LIST_MARKER_REACH);
+  const tail = source.slice(from, end);
+  return from === start && LIST_MARKER_ALONE.test(tail) || LIST_MARKER_AFTER_COLON.test(tail);
+}
+function splitSentences(text) {
+  const source = (text ?? "").trim();
+  if (!source) return [];
+  const sentences = [];
+  let start = 0;
+  let scanned = 0;
+  let sawLetter = false;
+  let i = 0;
+  while (i < source.length) {
+    if (!isStop(source[i])) {
+      i++;
+      continue;
+    }
+    let endsStrong = false;
+    while (i < source.length && isStop(source[i])) {
+      if (source[i] !== ".") endsStrong = true;
+      i++;
+    }
+    while (i < source.length && CLOSERS.has(source[i])) i++;
+    let next = i;
+    while (next < source.length && isSpace(source[next])) next++;
+    if (next === i || !startsSentence(source, next)) continue;
+    if (!sawLetter) sawLetter = LETTER.test(source.slice(scanned, i));
+    scanned = i;
+    if (!sawLetter) continue;
+    if (!endsStrong && (endsWithAbbreviation(source, i, digitFollows(source, next)) || endsWithListMarker(source, start, i))) continue;
+    sentences.push(source.slice(start, i).trim());
+    start = i;
+    sawLetter = false;
+  }
+  const rest = source.slice(start).trim();
+  if (rest) sentences.push(rest);
+  return sentences;
+}
+
+export { splitSentences };

package/dist/site-cache.d.ts

@@ -27,6 +27,8 @@ export declare const SITE_CACHE_TAGS: {
     readonly taxonomy: 'editorial-taxonomy';
     /** Portfolio items (agency-site-kit). */
     readonly portfolio: 'portfolio';
+    /** Products, services, events and membership plans (commerce-kit). */
+    readonly commerce: 'commerce';
 };
 export type SiteCacheTag = (typeof SITE_CACHE_TAGS)[keyof typeof SITE_CACHE_TAGS];
 /** The body Sonor POSTs to the revalidation route. */

package/dist/site-cache.js

@@ -12,7 +12,9 @@ var SITE_CACHE_TAGS = {
   /** Article categories and tags. */
   taxonomy: "editorial-taxonomy",
   /** Portfolio items (agency-site-kit). */
-  portfolio: "portfolio"
+  portfolio: "portfolio",
+  /** Products, services, events and membership plans (commerce-kit). */
+  commerce: "commerce"
 };
 function isSiteRevalidatePong(body) {
   return typeof body === "object" && body !== null && body.ok === true && body.ping === true;

package/dist/site-cache.mjs

@@ -10,7 +10,9 @@ var SITE_CACHE_TAGS = {
   /** Article categories and tags. */
   taxonomy: "editorial-taxonomy",
   /** Portfolio items (agency-site-kit). */
-  portfolio: "portfolio"
+  portfolio: "portfolio",
+  /** Products, services, events and membership plans (commerce-kit). */
+  commerce: "commerce"
 };
 function isSiteRevalidatePong(body) {
   return typeof body === "object" && body !== null && body.ok === true && body.ping === true;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.4.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, how a proposal's site plan counts its pages, what separates an error page from a page's content, and which stored JSON-LD is a template's unfilled placeholder. Pure functions, no dependencies.",
+  "version": "2.6.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, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, and which Sonor records Signal reads into a project's knowledge and the address each one is stored under. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -100,6 +100,16 @@
       "import": "./dist/schema-placeholders.mjs",
       "require": "./dist/schema-placeholders.js"
     },
+    "./sentences": {
+      "types": "./dist/sentences.d.ts",
+      "import": "./dist/sentences.mjs",
+      "require": "./dist/sentences.js"
+    },
+    "./knowledge": {
+      "types": "./dist/knowledge.d.ts",
+      "import": "./dist/knowledge.mjs",
+      "require": "./dist/knowledge.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {