@sonordev/contracts 2.7.1 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 2.9.0
+
+A minor release: three new entries, `@sonordev/contracts/page-titles`, `@sonordev/contracts/broadcast-layouts` and `@sonordev/contracts/publication-branding`. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/page-titles`**: what a page is called when a list, a sitemap or a case study needs its own name and not its whole title, so every one of them reads the same.
+  - `titleHead(title)` returns the title without its trailing " | Brand". Stray pipes are repaired first (a run of pipes with only whitespace between them is one separator, and a leading or trailing pipe is dropped), then only the last " | " segment goes, using `seo-meta`'s `stripTitleSuffix`. "Roof Repair | | Example Roofing" is "Roof Repair".
+  - `slugLabel(input)` makes a readable label from a slug, a file name or a path when a page has no title: "ac-replacement" is "AC Replacement", "faq" is "FAQ", "smith-and-smith" is "Smith and Smith", "homes-in-ky" is "Homes in KY". It knows acronyms, US state codes, small words and part numbers, and never throws on a malformed %-escape. "mt" is read by position: last it's Montana ("billings-mt" is "Billings MT"), and before another word it's Mount ("mt-adams" is "Mt Adams").
+  - `isRoutePlaceholder(value)` says whether a value, or any "/"-separated segment of it, is a route placeholder such as `:slug`, `[slug]` or `[[...rest]]`, so a page's pattern never ends up as its name.
+- **New entry `@sonordev/contracts/broadcast-layouts`**: which Broadcast card compositions are drawn, and what a retired one draws as, so the API, its agents and the dashboard can't disagree.
+  - `CARD_LAYOUTS` is every layout ID a stored row may carry (`stacked`, `headline`, `split`, `anchor`) and `ARTICLE_COVER_LAYOUTS` is the two that are drawn: centered `headline` and low `anchor`. Nothing is top-aligned.
+  - `RETIRED_CARD_LAYOUTS` and `normalizeArticleCoverLayout` draw a stored `stacked` as `anchor` and `split` as `headline`. `isCardLayoutId`, `isArticleCoverLayoutId` and `isRetiredCardLayoutId` are the checks, and `CARD_LAYOUT_LABELS` and `CARD_LAYOUT_OPTIONS` the names.
+  - `PUBLICATION_CARD_LAYOUTS` is what a publication-branding change may choose and `SAVED_PUBLICATION_CARD_LAYOUTS` what a saved profile may still carry.
+  - `BROADCAST_STYLES` lists the shared Broadcast looks.
+  - `REVIEW_CARD_VARIATIONS` (Signature and Framed), `normalizeReviewCardVariation` (a retired `spotlight` draws as Signature) and `reviewCardVariationFromDigest`, which draws each review's composition from the SHA-256 of `reviewCompositionSeed(projectId, reviewId)` so it never moves.
+- **New entry `@sonordev/contracts/publication-branding`**: what a project's publication branding may hold and what a change may set.
+  - `createPublicationBrandingValidator({ isBlockedHost })` returns `validatePublicationBranding`, `validatePublicationBrandingPatch` and `mergePublicationBrandingPatch`, bound to the caller's own private-address guard. A change may only choose a card layout that's drawn today; a saved profile still reads a retired one.
+  - `PublicationBrandingValidationError` names the refused field.
+  - The editorial charter (`parsePublicationCharter`, `parseSiteCharters`, `publicationCharterFor`, `publicationCharterContext`), `safeFontStack`, `containsControlCharacters` and `EMAIL_SAFE_FONTS`, plus the profile's types, platforms and field lists.
+
+## 2.8.0
+
+A minor release: two new entries, `@sonordev/contracts/business-claims` and `@sonordev/contracts/outreach`. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/business-claims`**: what an outbound email or text may say about a business, checked the same way where it's written and where it's sent.
+  - `checkOutboundCopy(copy, ctx)` sorts what it finds into `blocking` (refused outright), `flags` (a person looks before it sends) and `style` (never blocks), and returns the body as the reader sees it in `plain`. It reads the copy sentence by sentence after rendering HTML to text and decoding entities once.
+  - `PLATFORM_BANNED_CLAIMS` lists the claims no business's outreach may make. A business adds its own through `ctx.rules`.
+  - `OutboundClaimReview`, `readOutboundClaimReview` and `unsettledFlags` are the stored record of a check and the rule for when it's settled. `outboundRefusalMessage` is the one wording of a refusal.
+  - `readBackVerdict(intended, read)` says whether a sent email arrived intact.
+  - The quote, price and number helpers (`normalizeForQuote`, `quoteFoundIn`, `checkQuotedPrice`, `numbersGrounded`), `decodeHtmlEntities`, `removeDashes`, `outboundPlainText` and `isWriterNote` are exported so nothing re-implements them.
+- **New entry `@sonordev/contracts/outreach`**: what a segment of outreach is and who may turn one on.
+  - `outreachSegment`, `parseOutreachSegmentKey`, `isGrantableSegmentKey` and `outreachSegmentLabel` build, read and label segment keys. `prospectIndustry` and `normalizeIndustry` decide the industry, and `narrativeFingerprint` the pitch.
+  - `SegmentGrant`, `readSegmentGrants`, `activeSegmentGrant`, `segmentGrantCovers` and `grantEvidenceRefusal` read a person's standing approval of a segment and check it against the approvals it stands on. `GRADUATION_BAR` is the one bar a segment earns its own sending by.
+  - `segmentGranterEligible`, `PUBLIC_MAILBOX_DOMAINS`, `isPublicMailboxDomain` and `dripRowDisposition` round it out.
+
 ## 2.7.1
 
 - Preserve article photo source identity during duplicate detection when a responsive image optimizer rewrites the displayed URL.

package/README.md

@@ -32,6 +32,11 @@ pnpm add @sonordev/contracts
 | `@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 |
+| `@sonordev/contracts/business-claims` | What an outbound email or text may say about a business (`checkOutboundCopy`), the stored review of what it claimed and when that review is settled, and whether a sent email arrived intact (`readBackVerdict`) | the Sonor API checks again on the bytes it sends, Signal checks what its writers and agents file |
+| `@sonordev/contracts/outreach` | What a segment of outreach is (pitch, sending mailbox, prospect industry), who may turn one on, what a turned-on segment covers, and what a drip's ledger row means for its lead | Signal writes and reads segment grants, the Sonor API checks the same grant before it sends |
+| `@sonordev/contracts/page-titles` | A page's own name: its title without the brand (`titleHead`), a readable label from a slug (`slugLabel`), and whether a value is a route placeholder like `:slug` (`isRoutePlaceholder`) | Signal's site-architecture writer, the agency site kit's portfolio components |
+| `@sonordev/contracts/broadcast-layouts` | Which Broadcast card layouts are drawn (centered `headline`, low `anchor`), which retired IDs still read and what each draws as (`normalizeArticleCoverLayout`), the Broadcast styles, and the review compositions with the frozen draw that gives each review its own (`reviewCardVariationFromDigest`) | the Sonor API's card renderers and settings, Signal's agent tools, the dashboard's pickers |
+| `@sonordev/contracts/publication-branding` | What a publication's branding may hold and what a change may set (`createPublicationBrandingValidator`), how a change merges, the editorial charter, and safe font stacks | the Sonor API stores and resolves it, Signal checks an agent's change before filing it, the dashboard edits it |
 
 ## Schema placeholders
 
@@ -418,6 +423,316 @@ const batch = [...removed, ...changed].slice(0, KNOWLEDGE_SYNC_MAX_PAGES)
 // removals first, so the cut drops changed pages before any removal
 ```
 
+## The business-claims contract
+
+An email that goes out under a business's name can't promise what the
+business never said. Every writer (a model, an agent, a person's own
+template) and every sender checks copy with the same function, so a
+sentence refused where it's written is refused again where it's sent.
+
+```ts
+import { checkOutboundCopy } from '@sonordev/contracts/business-claims'
+
+const check = checkOutboundCopy(
+  { subject: 'A quick idea for your site', body, format: 'text', channel: 'email' },
+  { author: 'signal', rules, claims },
+)
+check.blocking // refused outright
+check.flags    // needs a person's look before it sends
+check.style    // house style, never blocks
+check.plain    // the body as the reader sees it
+```
+
+- **Who wrote it.** `author` is `'signal'` (copy a model wrote), `'agent'`
+  (an agent's own copy, the strictest set) or `'operator'` (a person's fixed
+  template). Operator copy gets the blocking set only. An author it doesn't
+  know is checked as an agent.
+- **Blocking.** An empty subject or body, a merge tag that never rendered
+  (`{{first_name}}`, `[Company]`), a claim no business may make
+  (`PLATFORM_BANNED_CLAIMS`: guaranteed rankings, top-3 or map pack spots
+  or results, "#1 on Google",
+  "risk free", fake scarcity, implied Google endorsement, and any promise
+  that they'll pay nothing or get their money back), the business's own
+  banned claims and the pitch's forbidden phrases, a price that matches none
+  the business publishes, and a word that mixes alphabets. An agent's own copy
+  is also refused for dashes and for unsafe HTML.
+- **Flags.** A price it can't verify, a number nothing backs, a citation that
+  doesn't match what it cites, a banned claim that a negation takes back, a
+  note the writer left to itself, and a number an agent took from its
+  research. Research about the recipient backs a number only in a sentence
+  about the recipient (`claimSubjectOf`). It never backs one about the sender.
+  A clause that names nobody ("the measured performance score is 61") counts
+  as the recipient's only when their research carries that number, and a
+  subject line may repeat a number the body backs that way.
+- **Rules come from the caller.** `rules` carries the business's published
+  prices, banned claims, forbidden phrases, verified facts and its own names,
+  resolved before the call, so no business data lives in the package. Price
+  and banned-claim rules run only when `rules` is set.
+- **Findings are stable.** Each finding's `id` is a hash of its code, its
+  sentence and the match (`outboundFindingId`), so a person's acknowledgement
+  of one sentence never carries over to a rewritten one.
+- **The stored review.** `OutboundClaimReview` is what was checked, against
+  which rules, and which flags a person acknowledged.
+  `readOutboundClaimReview(value)` reads a stored one defensively, and
+  `unsettledFlags(review)` lists the flags nobody has settled yet. A sender
+  refuses while that list isn't empty.
+- **The refusal.** `outboundRefusalMessage(findings)` is the one wording for
+  what's wrong and how to fix it, numbered and plain.
+- **Read-back.** `readBackVerdict(intended, read)` compares the email a
+  mailbox says it sent with the one that was meant: `verified` only when the
+  whole intended text arrived (a footer added after it is fine), otherwise
+  `empty`, `mismatch` or `unreadable`.
+- **Shared helpers.** The same normalizers the checker uses are exported for
+  anything that grounds a quote, price or number in a source
+  (`normalizeForQuote`, `quoteFoundIn`, `checkQuotedPrice`,
+  `numbersGrounded`), plus `decodeHtmlEntities`, `removeDashes`,
+  `outboundPlainText` and `isWriterNote`.
+
+`BUSINESS_CLAIMS_CONTRACT_VERSION` is bumped when the stored review's shape
+changes incompatibly.
+
+## The outreach contract
+
+Outreach earns the right to send on its own one segment at a time. A segment
+is one pitch, sent from one mailbox, to one kind of business. Both the API
+that writes outreach and the one that sends it read segments by these rules,
+so they can't disagree about what a person turned on.
+
+- **Segment keys.** `outreachSegment({ source, narrativeId, mailboxId,
+  industry })` builds one: `drip:<pitch id>@<mailbox id>|<industry>` for a
+  drip, or `mcp:-|<industry>` for an agent's one-off email, which is counted
+  but never turned on. `parseOutreachSegmentKey(key)` reads a key strictly
+  and returns `null` for anything else, so a caller-chosen key never reaches
+  storage. `isGrantableSegmentKey(key)` is true only for a drip segment with a
+  known industry. `outreachSegmentLabel` is the one human label.
+- **Industry.** `prospectIndustry(prospect)` picks the prospect's industry
+  and `normalizeIndustry(value)` folds it to one key ("Roofing Contractors"
+  and "roofing" are the same segment). A prospect with none is
+  `UNSPECIFIED_INDUSTRY`, and those always wait for a person.
+- **The pitch's fingerprint.** `narrativeFingerprint(narrative)` hashes the
+  pitch fields only (`NARRATIVE_PITCH_FIELDS`). Rewriting the pitch changes
+  it and lapses the segment. Renaming it, switching it off and on, or
+  tightening its forbidden phrases doesn't.
+- **States.** `SEGMENT_STATES` is `ungranted`, `granted`, `paused` (it
+  stopped itself), `lapsed` (the pitch changed) and `revoked`.
+- **Grants.** `SegmentGrant` is a person's standing approval of one segment,
+  either from approving its first email unedited (`first_email`) or by
+  accepting it once the segment earned it (`earned`).
+  `readSegmentGrants(settings)` and `activeSegmentGrant(settings, key)` read
+  them. `segmentGrantCovers(grant, row)` says whether a grant covers one
+  email: not when it's revoked or paused, names someone else, was written
+  before the grant, has a different pitch fingerprint or sends from another
+  mailbox.
+- **Evidence.** `grantEvidenceRefusal(grant, rows, scope)` checks the
+  approvals a grant stands on and returns why it can't be trusted, or `null`.
+  A grant that fails counts as no grant, so one written into settings by hand
+  never sends anything.
+- **The bar.** `GRADUATION_BAR` is the one track record that earns sending
+  without a click per email: at least 5 measured, at least 70% of them won,
+  and none that went wrong without being undone. An earned grant needs
+  `GRADUATION_BAR.minMeasured` approvals on record.
+- **Who may turn one on.** `segmentGranterEligible(roles)`: never an agent;
+  otherwise an owner or admin of the project, its organization or the agency
+  that manages it.
+- **Company domains.** `PUBLIC_MAILBOX_DOMAINS` and
+  `isPublicMailboxDomain(value)`: free mailbox providers, which never count as
+  a company's domain.
+- **A drip's row.** `dripRowDisposition(row)` says what a drip's ledger row
+  means for its lead: `live`, `sent`, `retire`, `declined` or `refile`. A
+  status it doesn't know reads as `live`, so a lead is never written to twice.
+
+`OUTREACH_CONTRACT_VERSION` is bumped when a grant's shape or the segment key
+changes incompatibly.
+
+## The page-titles contract
+
+A page's title is its own name followed by the brand: "AC Repair | Example
+HVAC". A list of pages, a sitemap or a case study wants the name alone, and
+the usual shortcuts get it wrong. Capitalizing each word of a slug turns
+"ac-replacement" into "Ac Replacement", "faq" into "Faq" and
+"smith-and-smith" into "Smith And Smith". A title with a stray second pipe
+ships as "Loans | | Brand". `titleHead`, `slugLabel` and `isRoutePlaceholder`
+are the one set of rules, so every list reads the same.
+
+```ts
+import { isRoutePlaceholder, slugLabel, titleHead } from '@sonordev/contracts/page-titles'
+
+titleHead('FHA Home Loans | | Example Mortgage') // 'FHA Home Loans'
+slugLabel('/services/hvac-repair/')              // 'HVAC Repair'
+isRoutePlaceholder('/floor-plans/:slug')         // true
+```
+
+- **`titleHead(title)`** is the title without its trailing " | Brand". Only
+  the last " | " segment is the brand, so "1 Bedroom | 1BR 1BA | Example
+  Apartments" is "1 Bedroom | 1BR 1BA". The cut is the one `seo-meta`'s
+  `stripTitleSuffix` makes.
+- **Stray pipes are repaired first.** A run of pipes with only whitespace
+  between them is one separator ("Roof Repair | | Example Roofing" reads as
+  "Roof Repair | Example Roofing"), and a leading or trailing pipe is dropped
+  ("Pricing |" is "Pricing"). Whitespace is trimmed and collapsed.
+- **No separator, no cut.** A title without one comes back as written. It
+  can't tell a brand from a name, so a title that's only a brand stays that
+  brand, and a dash ("AC Repair - Example HVAC") isn't a brand separator.
+  Empty, whitespace-only, `null` and `undefined` input give `""`.
+- **Apply it once.** A title with two or more separators loses one segment
+  per call, so the output of `titleHead` isn't a title to run it on again.
+- **`slugLabel(input)`** is for the rare label that has to come from a slug,
+  a file name or a path because the page has no title. Prefer `titleHead`:
+  a title is what the page was written with, and a slug is a guess at it.
+- **Which part it reads.** The last non-empty path segment, after dropping a
+  `https://host` origin, a query or a hash, and a trailing `.html`, `.htm`,
+  `.php` or `.aspx`. %-escapes are decoded without ever throwing: a malformed
+  one stays as written. Words split on `-`, `_`, `+` and whitespace.
+- **How each word is cased**, by the first rule that fits:
+  - an acronym is upper case: `ac`, `ai`, `aeo`, `api`, `cms`, `crm`, `faq`,
+    `fsbo`, `hvac`, `jl`, `llc`, `llp`, `mls`, `pdf`, `pllc`, `ppc`, `roi`,
+    `seo`, `ui`, `ux` and `usa`. The plural `faqs` is "FAQs";
+  - a stand-alone two-letter US state or DC code is upper case
+    ("covington-ky" is "Covington KY"). Codes that are ordinary words as
+    often as not stay words: `in`, `or`, `me`, `hi`, `id`, `la`, `ma`, `pa`,
+    `al`, `de` and `co`. `mt` goes by its position: as the last word it's
+    Montana ("billings-mt" is "Billings MT"), and with a word after it it's
+    Mount ("mt-adams" is "Mt Adams", "academy-of-mt-adams" is "Academy of Mt
+    Adams"). `us` isn't a state: "about-us" is "About Us";
+  - a word with a digit keeps its case, and gains a capital only when it
+    starts with a letter: "c1" is "C1", "075ct" and "1003" stay;
+  - a small word is lower case unless it's first: `a`, `an`, `and`, `at`,
+    `by`, `for`, `in`, `of`, `on`, `or`, `the`, `to`, `vs`, `with`;
+  - anything else gets a capital first letter and lower case after it.
+  The first word of a label is always capitalized, and an acronym stays upper
+  case there.
+- **Nothing to label gives `""`.** `""`, `"/"`, `"?x=1"` and a bare origin
+  all give an empty string. Naming the home page is the caller's job.
+- **Stable.** Running a label back through `slugLabel` gives the same label,
+  as long as its words follow the rules above. A brand's own capitalization
+  ("DeWalt") is the exception.
+- **`isRoutePlaceholder(value)`** is true when the value, or any
+  "/"-separated segment of it, is a framework route placeholder: `:slug`,
+  `:Slug`, `:id?`, `[slug]`, `[...rest]` or `[[...rest]]`. A placeholder is a
+  single token with no spaces, so ordinary text that contains a colon or a
+  bracket isn't one ("Update: new hours", "FAQ / [draft] notes"). Nullish and
+  empty values are false.
+
+Known limits. A slug carries no capitalization or punctuation, so "DeWalt"
+reads "Dewalt", "joes-pizza" reads "Joes Pizza", and an `index.html` reads
+"Index". A slug with `mt` anywhere but last reads it as Mount
+("billings-mt-homes" reads "Billings Mt Homes"), since position is all that
+tells Montana from Mount. A bare `[draft]` is a placeholder, because nothing
+tells it from `[slug]`. Only the pipe is a brand separator, the way
+`stripTitleSuffix` has it.
+
+## The broadcast-layouts contract
+
+A Broadcast post is centered or low, never top-aligned. The title-on-top
+composition was retired, but posts and settings saved before that still name
+it, so there are two lists: every ID a stored row may carry, and the IDs
+that are drawn. A retired ID keeps validating and draws as its replacement.
+
+```ts
+import { createHash } from 'node:crypto'
+import {
+  ARTICLE_COVER_LAYOUTS, CARD_LAYOUTS, isCardLayoutId, normalizeArticleCoverLayout,
+  normalizeReviewCardVariation, reviewCardVariationFromDigest, reviewCompositionSeed,
+} from '@sonordev/contracts/broadcast-layouts'
+
+CARD_LAYOUTS                                // ['stacked', 'headline', 'split', 'anchor']
+ARTICLE_COVER_LAYOUTS                       // ['headline', 'anchor']
+isCardLayoutId('stacked')                   // true: an old post still reads
+normalizeArticleCoverLayout('stacked')      // 'anchor'
+normalizeArticleCoverLayout('split')        // 'headline'
+normalizeReviewCardVariation('spotlight')   // 'signature'
+
+// On the server: a review's composition, stable for its identity.
+const digest = createHash('sha256').update(reviewCompositionSeed(projectId, reviewId)).digest()
+reviewCardVariationFromDigest(digest)       // 'signature' or 'frame'
+```
+
+- **`CARD_LAYOUTS`** is every layout ID a stored row, a saved setting or a
+  request may carry, retired ones included. **`ARTICLE_COVER_LAYOUTS`** is
+  what's drawn and offered. Both orders are part of the contract: rotation
+  picks by index, and a refusal lists the IDs in order.
+- **`RETIRED_CARD_LAYOUTS`** maps each retired ID to what it draws as
+  (`stacked` to `anchor`, `split` to `headline`).
+  **`normalizeArticleCoverLayout`** applies it and returns anything else as
+  it came, so a caller still checks `isCardLayoutId` (or passes `auto`)
+  before rendering. Only an own key of the map is retired, so `"toString"`
+  isn't.
+- **`CARD_LAYOUT_LABELS`** names the drawn layouts and
+  **`CARD_LAYOUT_OPTIONS`** serves them Anchor first.
+- **`PUBLICATION_CARD_LAYOUTS`** is what a publication-branding change may
+  choose (`auto` or a drawn layout). **`SAVED_PUBLICATION_CARD_LAYOUTS`** is
+  what a saved profile may carry (`auto` or any readable ID).
+- **`BROADCAST_STYLES`** is the shared look for article, review and generated
+  post artwork (`glass` by default).
+- **`REVIEW_CARD_VARIATIONS`** is the review compositions drawn, Signature
+  and Framed. **`normalizeReviewCardVariation`** draws a retired `spotlight`
+  as Signature and anything unknown as the default, Signature.
+  **`isReviewCardVariation`** is the strict check for a request that must
+  name a drawn one.
+- **A review's composition never moves.** It's drawn from the SHA-256 of
+  `reviewCompositionSeed(projectId, reviewId)`, never from anything a person
+  can edit. `reviewCardVariationFromDigest` reads the first four bytes
+  against the frozen v1 list (`REVIEW_CARD_VARIATION_V1_DRAW`); a review that
+  drew the retired Spotlight redraws between the drawn two from the next four
+  bytes, so no other review changes. The hash stays with the caller, so the
+  contract needs no `crypto`.
+
+Changing a list's order or the v1 draw list reshuffles stored posts, so treat
+both as a breaking change and bump `BROADCAST_LAYOUTS_CONTRACT_VERSION`.
+
+## The publication-branding contract
+
+A project's publication branding is one stored profile: identity (names,
+publisher, logos), colors, type, editorial direction (the Broadcast style,
+the card layout, the charter) and newsletter settings, each of which a
+channel (email, social, a single network) can override. The API that saves it
+and the agent tools that propose changes to it have to agree exactly on what's
+valid, so the validator lives here once.
+
+```ts
+import { createPublicationBrandingValidator } from '@sonordev/contracts/publication-branding'
+
+// Bind it once, to the server's own private-address guard.
+const branding = createPublicationBrandingValidator({ isBlockedHost })
+
+branding.validatePublicationBrandingPatch({ colors: { primary: '#ABC' } })
+// { colors: { primary: '#aabbcc' } }
+branding.validatePublicationBrandingPatch({ editorial: { cardLayout: 'stacked' } })
+// throws: publication_branding.editorial.cardLayout: choose auto, headline, anchor
+branding.mergePublicationBrandingPatch(saved, { identity: { logos: { dark: null } } })
+// saved, minus that one override
+```
+
+- **`createPublicationBrandingValidator({ isBlockedHost })`** returns the
+  validator. A URL leaf must be a public HTTPS URL without credentials;
+  whether its host is private (loopback, a LAN range, link-local,
+  `localhost`) is the caller's guard, because that check needs Node. It gets
+  `new URL(value).hostname`, so IPv6 keeps its brackets.
+- **`validatePublicationBranding`** reads a whole saved profile.
+  **`validatePublicationBrandingPatch`** reads a change: a leaf set to `null`
+  clears that override, and a card layout must be one that's drawn today.
+  A saved profile may still name a retired layout.
+- **`mergePublicationBrandingPatch(saved, change)`** applies a change leaf by
+  leaf and prunes containers it empties. No saved profile reads as
+  `{ version: 1 }`, and a change that sets nothing returns the profile as it
+  was. **`mergePublicationBrandingLayers`** is the same leaf-wise merge for
+  resolving layers.
+- **Refusals name the field.** A `PublicationBrandingValidationError` carries
+  the path (`publication_branding.platforms.email.colors.primary`) and says
+  what's allowed. A charter set on a channel override is a plain `Error`: a
+  charter belongs to the publication or a site.
+- **The editorial charter** (`parsePublicationCharter`, `parseSiteCharters`,
+  `publicationCharterFor`, `publicationCharterContext`) is data-only
+  direction: who the publication is for, what they're deciding, the proof it
+  holds itself to. It's never evidence of expertise.
+- **`safeFontStack`** keeps a font stack as data ("'Brand Display',serif"),
+  never a stylesheet fragment, and `EMAIL_SAFE_FONTS` is what an email
+  fallback may name.
+
+The stored shape's version is `PUBLICATION_BRANDING_VERSION`. Resolving a
+profile against a project's own colors and its measured site design stays in
+the Sonor API.
+
 ## Why it exists
 
 A rule that lives in several copies is how two of them end up disagreeing.

package/dist/broadcast-layouts.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Broadcast layouts: which compositions a Broadcast card draws, which retired
+ * IDs stay readable and what each one draws as, the Broadcast styles, and the
+ * review card variations with the frozen draw that gives each review its
+ * composition. Sonor's APIs and dashboard import it as
+ * `@sonordev/contracts/broadcast-layouts`.
+ *
+ * Why it exists: a post is centered (`headline`) or low (`anchor`), never
+ * top-aligned. Retiring the top-aligned compositions meant changing the same
+ * lists in three places (the Sonor API, Signal and the dashboard), and any one
+ * of them drifting would let an old ID reach a renderer or a picker. So the
+ * IDs, the retired-to-drawn map, the normalizers, the labels and the review
+ * draw live here once.
+ *
+ * Two lists, on purpose:
+ *  - CARD_LAYOUTS is every ID a stored row, a saved setting or a request may
+ *    carry. Retired IDs stay in it so old rows keep validating; they're
+ *    normalized on the way to a renderer.
+ *  - ARTICLE_COVER_LAYOUTS is what's drawn and offered. Nothing else is.
+ * Both orders are visible (rotation order and refusal messages), so they're
+ * part of the contract.
+ *
+ * Pure: no I/O, no Node built-ins. The review draw takes the SHA-256 digest
+ * of reviewCompositionSeed, which the caller hashes, so the hash stays with
+ * the server.
+ */
+/** Bumped when a stored ID here changes meaning. */
+export declare const BROADCAST_LAYOUTS_CONTRACT_VERSION = 1;
+/**
+ * Every composition ID a stored row, a saved setting or a request may carry.
+ *
+ * - `headline`: centered, the title set large.
+ * - `anchor`:   the background leads, the title sits low.
+ * - `stacked`:  retired 2026-10-14 (title pinned to the top, art below). Draws as `anchor`.
+ * - `split`:    retired (title and stage in columns). Draws as `headline`.
+ */
+export declare const CARD_LAYOUTS: readonly ['stacked', 'headline', 'split', 'anchor'];
+export type CardLayoutId = (typeof CARD_LAYOUTS)[number];
+/** The compositions Broadcast draws and offers: centered or low. Nothing is top-aligned. */
+export declare const ARTICLE_COVER_LAYOUTS: readonly ['headline', 'anchor'];
+export type ArticleCoverLayoutId = (typeof ARTICLE_COVER_LAYOUTS)[number];
+export type RetiredCardLayoutId = Exclude<CardLayoutId, ArticleCoverLayoutId>;
+/** Each retired layout ID, and the composition it draws as. */
+export declare const RETIRED_CARD_LAYOUTS: Readonly<Record<RetiredCardLayoutId, ArticleCoverLayoutId>>;
+/** A readable layout ID, retired ones included. The check every input boundary uses. */
+export declare const isCardLayoutId: (value: unknown) => value is CardLayoutId;
+/** A layout that's drawn and offered today. */
+export declare const isArticleCoverLayoutId: (value: unknown) => value is ArticleCoverLayoutId;
+/** A retired layout ID (an own key of RETIRED_CARD_LAYOUTS, never an inherited one). */
+export declare const isRetiredCardLayoutId: (value: unknown) => value is RetiredCardLayoutId;
+/**
+ * Which composition a layout ID draws. A retired ID becomes what it draws as;
+ * anything else is returned as it came, so callers check isCardLayoutId (or
+ * pass `auto` through) before rendering. Every renderer reads its layout
+ * through here, so a retired ID never reaches one.
+ */
+export declare function normalizeArticleCoverLayout(layout: CardLayoutId): ArticleCoverLayoutId;
+export declare function normalizeArticleCoverLayout<T>(layout: T): T | ArticleCoverLayoutId;
+/** What each drawn layout is called wherever a person picks one. */
+export declare const CARD_LAYOUT_LABELS: Readonly<Record<ArticleCoverLayoutId, string>>;
+/** The layout choices the API serves to pickers and agents, Anchor first. */
+export declare const CARD_LAYOUT_OPTIONS: ReadonlyArray<{
+    id: ArticleCoverLayoutId;
+    label: string;
+}>;
+/** A publication's card layout when it doesn't pin one: rotate. */
+export declare const AUTO_CARD_LAYOUT: 'auto';
+export type PublicationCardLayout = CardLayoutId | typeof AUTO_CARD_LAYOUT;
+/** What a publication-branding write may choose: rotate, or a drawn layout. */
+export declare const PUBLICATION_CARD_LAYOUTS: readonly ["auto", "headline", "anchor"];
+/** What a saved publication-branding profile may carry: a write's choices plus the retired IDs. */
+export declare const SAVED_PUBLICATION_CARD_LAYOUTS: readonly ["auto", "stacked", "headline", "split", "anchor"];
+/**
+ * The shared Broadcast look for article, review and generated post artwork.
+ * One choice per project (stored as `articleStyle`, its legacy wire name).
+ *
+ * - `glass`:     the background full bleed, the words on a frosted card.
+ * - `editorial`: paper, a serif headline, the image framed like a magazine plate.
+ * - `poster`:    one flat accent field, condensed type, big numbers.
+ * - `cinematic`: the image as a widescreen still over solid ground.
+ * - `blueprint`: a drawing sheet, with a grid, mono labels and a title block.
+ * - `focus`:     real project photos, a dark reading gradient and circular details.
+ */
+export declare const BROADCAST_STYLES: readonly ['glass', 'editorial', 'poster', 'cinematic', 'blueprint', 'focus'];
+export type BroadcastStyleId = (typeof BROADCAST_STYLES)[number];
+export declare const DEFAULT_BROADCAST_STYLE: BroadcastStyleId;
+export declare const isBroadcastStyleId: (value: unknown) => value is BroadcastStyleId;
+/**
+ * The review compositions Broadcast draws: `signature` (photo up top, the
+ * quote low) and `frame` (centered). Order matters: a review whose v1 draw
+ * was retired redraws by index into this list.
+ */
+export declare const REVIEW_CARD_VARIATIONS: readonly ['signature', 'frame'];
+export type ReviewCardVariation = (typeof REVIEW_CARD_VARIATIONS)[number];
+/** A review composition when none is chosen, or an unknown one is asked for. */
+export declare const DEFAULT_REVIEW_CARD_VARIATION: ReviewCardVariation;
+/** Each retired review variation, and what it draws as. `spotlight` pinned the quote to the top; retired 2026-10-14. */
+export declare const RETIRED_REVIEW_CARD_VARIATIONS: Readonly<Record<'spotlight', ReviewCardVariation>>;
+/** What each review variation is called wherever a person picks one. */
+export declare const REVIEW_CARD_VARIATION_LABELS: Readonly<Record<ReviewCardVariation, string>>;
+/** The review variation choices, in REVIEW_CARD_VARIATIONS order. */
+export declare const REVIEW_CARD_VARIATION_OPTIONS: ReadonlyArray<{
+    id: ReviewCardVariation;
+    label: string;
+}>;
+/** A review variation that's drawn today. Strict: a retired one isn't. */
+export declare const isReviewCardVariation: (value: unknown) => value is ReviewCardVariation;
+/**
+ * The review composition to draw for a stored or requested value: a drawn
+ * one as it is, a retired one as what it draws as, anything else (null, '',
+ * an unknown string) as the default.
+ */
+export declare function normalizeReviewCardVariation(value: unknown): ReviewCardVariation;
+/**
+ * The v1 draw list, frozen. A review's composition belongs to its immutable
+ * identity, so changing this list (or its order) would reshuffle every
+ * review's card. New compositions get a new seed version, never an edit here.
+ */
+export declare const REVIEW_CARD_VARIATION_V1_DRAW: readonly ['signature', 'spotlight', 'frame'];
+/**
+ * What a review's composition is drawn from: the project and the review, and
+ * nothing a person can edit (platform, artwork, copy and brand never move it).
+ * Hash this string with SHA-256 and pass the digest to
+ * reviewCardVariationFromDigest.
+ */
+export declare function reviewCompositionSeed(projectId: string, reviewId: string): string;
+/**
+ * The composition a review's digest draws. The first four bytes (big-endian)
+ * pick from the v1 list; a review that drew a retired composition redraws
+ * between the drawn ones from the next four, so no other review moves.
+ * `digest` is the SHA-256 of reviewCompositionSeed (a Node Buffer works).
+ */
+export declare function reviewCardVariationFromDigest(digest: ArrayLike<number>): ReviewCardVariation;

package/dist/broadcast-layouts.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// src/contracts/broadcast-layouts.ts
+var BROADCAST_LAYOUTS_CONTRACT_VERSION = 1;
+var own = (record, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(record, key);
+var CARD_LAYOUTS = ["stacked", "headline", "split", "anchor"];
+var ARTICLE_COVER_LAYOUTS = ["headline", "anchor"];
+var RETIRED_CARD_LAYOUTS = {
+  stacked: "anchor",
+  split: "headline"
+};
+var isCardLayoutId = (value) => typeof value === "string" && CARD_LAYOUTS.includes(value);
+var isArticleCoverLayoutId = (value) => typeof value === "string" && ARTICLE_COVER_LAYOUTS.includes(value);
+var isRetiredCardLayoutId = (value) => own(RETIRED_CARD_LAYOUTS, value);
+function normalizeArticleCoverLayout(layout) {
+  return isRetiredCardLayoutId(layout) ? RETIRED_CARD_LAYOUTS[layout] : layout;
+}
+var CARD_LAYOUT_LABELS = {
+  headline: "Headline",
+  anchor: "Anchor"
+};
+var CARD_LAYOUT_OPTIONS = [
+  { id: "anchor", label: CARD_LAYOUT_LABELS.anchor },
+  { id: "headline", label: CARD_LAYOUT_LABELS.headline }
+];
+var AUTO_CARD_LAYOUT = "auto";
+var PUBLICATION_CARD_LAYOUTS = [AUTO_CARD_LAYOUT, ...ARTICLE_COVER_LAYOUTS];
+var SAVED_PUBLICATION_CARD_LAYOUTS = [AUTO_CARD_LAYOUT, ...CARD_LAYOUTS];
+var BROADCAST_STYLES = ["glass", "editorial", "poster", "cinematic", "blueprint", "focus"];
+var DEFAULT_BROADCAST_STYLE = "glass";
+var isBroadcastStyleId = (value) => typeof value === "string" && BROADCAST_STYLES.includes(value);
+var REVIEW_CARD_VARIATIONS = ["signature", "frame"];
+var DEFAULT_REVIEW_CARD_VARIATION = "signature";
+var RETIRED_REVIEW_CARD_VARIATIONS = {
+  spotlight: "signature"
+};
+var REVIEW_CARD_VARIATION_LABELS = {
+  signature: "Signature",
+  frame: "Framed"
+};
+var REVIEW_CARD_VARIATION_OPTIONS = REVIEW_CARD_VARIATIONS.map((id) => ({ id, label: REVIEW_CARD_VARIATION_LABELS[id] }));
+var isReviewCardVariation = (value) => typeof value === "string" && REVIEW_CARD_VARIATIONS.includes(value);
+function normalizeReviewCardVariation(value) {
+  if (isReviewCardVariation(value)) return value;
+  return own(RETIRED_REVIEW_CARD_VARIATIONS, value) ? RETIRED_REVIEW_CARD_VARIATIONS[value] : DEFAULT_REVIEW_CARD_VARIATION;
+}
+var REVIEW_CARD_VARIATION_V1_DRAW = ["signature", "spotlight", "frame"];
+function reviewCompositionSeed(projectId, reviewId) {
+  return JSON.stringify(["review-composition-v1", projectId, reviewId]);
+}
+var uint32BE = (bytes, offset) => (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+function reviewCardVariationFromDigest(digest) {
+  if (!digest || digest.length < 8) throw new RangeError("A review composition digest needs at least 8 bytes");
+  const drawn = REVIEW_CARD_VARIATION_V1_DRAW[uint32BE(digest, 0) % REVIEW_CARD_VARIATION_V1_DRAW.length];
+  return isReviewCardVariation(drawn) ? drawn : REVIEW_CARD_VARIATIONS[uint32BE(digest, 4) % REVIEW_CARD_VARIATIONS.length];
+}
+
+exports.ARTICLE_COVER_LAYOUTS = ARTICLE_COVER_LAYOUTS;
+exports.AUTO_CARD_LAYOUT = AUTO_CARD_LAYOUT;
+exports.BROADCAST_LAYOUTS_CONTRACT_VERSION = BROADCAST_LAYOUTS_CONTRACT_VERSION;
+exports.BROADCAST_STYLES = BROADCAST_STYLES;
+exports.CARD_LAYOUTS = CARD_LAYOUTS;
+exports.CARD_LAYOUT_LABELS = CARD_LAYOUT_LABELS;
+exports.CARD_LAYOUT_OPTIONS = CARD_LAYOUT_OPTIONS;
+exports.DEFAULT_BROADCAST_STYLE = DEFAULT_BROADCAST_STYLE;
+exports.DEFAULT_REVIEW_CARD_VARIATION = DEFAULT_REVIEW_CARD_VARIATION;
+exports.PUBLICATION_CARD_LAYOUTS = PUBLICATION_CARD_LAYOUTS;
+exports.RETIRED_CARD_LAYOUTS = RETIRED_CARD_LAYOUTS;
+exports.RETIRED_REVIEW_CARD_VARIATIONS = RETIRED_REVIEW_CARD_VARIATIONS;
+exports.REVIEW_CARD_VARIATIONS = REVIEW_CARD_VARIATIONS;
+exports.REVIEW_CARD_VARIATION_LABELS = REVIEW_CARD_VARIATION_LABELS;
+exports.REVIEW_CARD_VARIATION_OPTIONS = REVIEW_CARD_VARIATION_OPTIONS;
+exports.REVIEW_CARD_VARIATION_V1_DRAW = REVIEW_CARD_VARIATION_V1_DRAW;
+exports.SAVED_PUBLICATION_CARD_LAYOUTS = SAVED_PUBLICATION_CARD_LAYOUTS;
+exports.isArticleCoverLayoutId = isArticleCoverLayoutId;
+exports.isBroadcastStyleId = isBroadcastStyleId;
+exports.isCardLayoutId = isCardLayoutId;
+exports.isRetiredCardLayoutId = isRetiredCardLayoutId;
+exports.isReviewCardVariation = isReviewCardVariation;
+exports.normalizeArticleCoverLayout = normalizeArticleCoverLayout;
+exports.normalizeReviewCardVariation = normalizeReviewCardVariation;
+exports.reviewCardVariationFromDigest = reviewCardVariationFromDigest;
+exports.reviewCompositionSeed = reviewCompositionSeed;

package/dist/broadcast-layouts.mjs

@@ -0,0 +1,56 @@
+// src/contracts/broadcast-layouts.ts
+var BROADCAST_LAYOUTS_CONTRACT_VERSION = 1;
+var own = (record, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(record, key);
+var CARD_LAYOUTS = ["stacked", "headline", "split", "anchor"];
+var ARTICLE_COVER_LAYOUTS = ["headline", "anchor"];
+var RETIRED_CARD_LAYOUTS = {
+  stacked: "anchor",
+  split: "headline"
+};
+var isCardLayoutId = (value) => typeof value === "string" && CARD_LAYOUTS.includes(value);
+var isArticleCoverLayoutId = (value) => typeof value === "string" && ARTICLE_COVER_LAYOUTS.includes(value);
+var isRetiredCardLayoutId = (value) => own(RETIRED_CARD_LAYOUTS, value);
+function normalizeArticleCoverLayout(layout) {
+  return isRetiredCardLayoutId(layout) ? RETIRED_CARD_LAYOUTS[layout] : layout;
+}
+var CARD_LAYOUT_LABELS = {
+  headline: "Headline",
+  anchor: "Anchor"
+};
+var CARD_LAYOUT_OPTIONS = [
+  { id: "anchor", label: CARD_LAYOUT_LABELS.anchor },
+  { id: "headline", label: CARD_LAYOUT_LABELS.headline }
+];
+var AUTO_CARD_LAYOUT = "auto";
+var PUBLICATION_CARD_LAYOUTS = [AUTO_CARD_LAYOUT, ...ARTICLE_COVER_LAYOUTS];
+var SAVED_PUBLICATION_CARD_LAYOUTS = [AUTO_CARD_LAYOUT, ...CARD_LAYOUTS];
+var BROADCAST_STYLES = ["glass", "editorial", "poster", "cinematic", "blueprint", "focus"];
+var DEFAULT_BROADCAST_STYLE = "glass";
+var isBroadcastStyleId = (value) => typeof value === "string" && BROADCAST_STYLES.includes(value);
+var REVIEW_CARD_VARIATIONS = ["signature", "frame"];
+var DEFAULT_REVIEW_CARD_VARIATION = "signature";
+var RETIRED_REVIEW_CARD_VARIATIONS = {
+  spotlight: "signature"
+};
+var REVIEW_CARD_VARIATION_LABELS = {
+  signature: "Signature",
+  frame: "Framed"
+};
+var REVIEW_CARD_VARIATION_OPTIONS = REVIEW_CARD_VARIATIONS.map((id) => ({ id, label: REVIEW_CARD_VARIATION_LABELS[id] }));
+var isReviewCardVariation = (value) => typeof value === "string" && REVIEW_CARD_VARIATIONS.includes(value);
+function normalizeReviewCardVariation(value) {
+  if (isReviewCardVariation(value)) return value;
+  return own(RETIRED_REVIEW_CARD_VARIATIONS, value) ? RETIRED_REVIEW_CARD_VARIATIONS[value] : DEFAULT_REVIEW_CARD_VARIATION;
+}
+var REVIEW_CARD_VARIATION_V1_DRAW = ["signature", "spotlight", "frame"];
+function reviewCompositionSeed(projectId, reviewId) {
+  return JSON.stringify(["review-composition-v1", projectId, reviewId]);
+}
+var uint32BE = (bytes, offset) => (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+function reviewCardVariationFromDigest(digest) {
+  if (!digest || digest.length < 8) throw new RangeError("A review composition digest needs at least 8 bytes");
+  const drawn = REVIEW_CARD_VARIATION_V1_DRAW[uint32BE(digest, 0) % REVIEW_CARD_VARIATION_V1_DRAW.length];
+  return isReviewCardVariation(drawn) ? drawn : REVIEW_CARD_VARIATIONS[uint32BE(digest, 4) % REVIEW_CARD_VARIATIONS.length];
+}
+
+export { ARTICLE_COVER_LAYOUTS, AUTO_CARD_LAYOUT, BROADCAST_LAYOUTS_CONTRACT_VERSION, BROADCAST_STYLES, CARD_LAYOUTS, CARD_LAYOUT_LABELS, CARD_LAYOUT_OPTIONS, DEFAULT_BROADCAST_STYLE, DEFAULT_REVIEW_CARD_VARIATION, PUBLICATION_CARD_LAYOUTS, RETIRED_CARD_LAYOUTS, RETIRED_REVIEW_CARD_VARIATIONS, REVIEW_CARD_VARIATIONS, REVIEW_CARD_VARIATION_LABELS, REVIEW_CARD_VARIATION_OPTIONS, REVIEW_CARD_VARIATION_V1_DRAW, SAVED_PUBLICATION_CARD_LAYOUTS, isArticleCoverLayoutId, isBroadcastStyleId, isCardLayoutId, isRetiredCardLayoutId, isReviewCardVariation, normalizeArticleCoverLayout, normalizeReviewCardVariation, reviewCardVariationFromDigest, reviewCompositionSeed };