@sonordev/contracts 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 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.
+
 ## 2.7.0
 
 - Add `editorial-media`: shared section/takeaway text identities, article photo placement diagnostics, and source-image eligibility constants for APIs and site renderers.

package/README.md

@@ -3,6 +3,10 @@
 The rules Sonor's sites, APIs and dashboard have to agree on, as one package.
 Pure functions and types: no dependencies, no DOM, no network.
 
+The `editorial-media` placement resolver recognizes an image's canonical
+`data-sk-editorial-source` as well as its displayed `src`. Responsive image
+delivery can change URLs without inserting the same approved photo twice.
+
 ```bash
 pnpm add @sonordev/contracts
 ```
@@ -28,6 +32,8 @@ 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 |
 
 ## Schema placeholders
 
@@ -414,6 +420,127 @@ 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.
+
 ## Why it exists
 
 A rule that lives in several copies is how two of them end up disagreeing.

package/dist/business-claims.d.ts

@@ -0,0 +1,456 @@
+/** Bumped when a stored shape here (OutboundClaimReview) changes incompatibly. */
+export declare const BUSINESS_CLAIMS_CONTRACT_VERSION = 1;
+/**
+ * Decode HTML character references in one pass: named ones (the table
+ * above), decimal (') and hex ('). One pass, so a double-encoded
+ * "'" comes back as the literal "'" it was written as, never as
+ * "'". An invalid code point (zero, a surrogate, past U+10FFFF) is left as
+ * written, and   is a plain space.
+ */
+export declare function decodeHtmlEntities(text: string): string;
+/** A quote shorter than this (after normalizeForQuote) grounds nothing. */
+export declare const MIN_QUOTE_CHARS = 12;
+/**
+ * Text as a quote is compared: entities decoded (named, decimal and hex),
+ * compatibility forms folded (… is ...), invisible characters removed, curly
+ * quotes straight, every dash a hyphen with no space around it, "$ 40" as
+ * "$40", whitespace collapsed, lowercase. Applied to both sides, so a quote
+ * copied off the page matches however the page spelled its punctuation, and
+ * nothing else does.
+ */
+export declare function normalizeForQuote(text: unknown): string;
+/**
+ * The form every claim matcher reads: normalizeForQuote (NFKC, invisible
+ * characters removed, entities decoded, lowercase). Use it on a raw string
+ * you want to compare the way checkOutboundCopy does.
+ */
+export declare function normalizeMatchable(text: unknown): string;
+/**
+ * Where `needle` occurs in `haystack` as a whole span, or -1: never the start
+ * or the tail of a longer number ("$90" inside "$900", "$4,000" inside
+ * "$4,000,000", "200" inside "$1,200") and never a word cut in half. Both
+ * sides are already normalized (normalizeForQuote).
+ */
+export declare function wholeSpanAt(haystack: string, needle: string): number;
+/**
+ * Whether `quote` appears in the source text, verbatim after normalizeForQuote
+ * and as a whole span (wholeSpanAt: a quote that stops in the middle of a
+ * number or a word isn't the source's words). `normalizedSource` is already
+ * normalized (each source is normalized once). A quote shorter than
+ * `minChars` grounds nothing. A price keeps its punctuation here, so
+ * "$4,000" never matches "4 000".
+ */
+export declare function quoteFoundIn(quote: unknown, normalizedSource: string, minChars?: number): boolean;
+/** Dollar amounts in normalized text: "$4,000" is 4000, "$4k" is 4000, "$12.50" is 12.5. */
+export declare function moneyAmounts(normalized: string): number[];
+/**
+ * Words just before a price that make it a floor, a ceiling or one end of a
+ * range. A dash or "to" counts only after a number ("$1,000-$3,000"), never
+ * after a name ("Essential - $1,000" is a price list, not a range).
+ */
+export declare const PRICE_RANGE_BEFORE: RegExp;
+/** Just after a price: "+", or the other end of a range. */
+export declare const PRICE_RANGE_AFTER: RegExp;
+/**
+ * An offer's price checked against its quote: the price must appear in the
+ * quote exactly as written (after normalizeForQuote), as a whole span
+ * (wholeSpanAt: "$90" never passes against "$900"), and be a dollar amount or
+ * "free". A price that's one end of what the quote says ("$2,000" out of
+ * "$2,000 - $9,000", "$500" out of "starting at $500", "$25,000" out of
+ * "$25,000+") fails: the display has to carry the whole span. Returns min/max
+ * read from the amounts, or null when the price fails.
+ */
+export declare function checkQuotedPrice(display: unknown, quote: unknown): {
+    min?: number;
+    max?: number;
+} | null;
+/** The numbers written in normalized text, commas and trailing punctuation dropped: "1,200." is "1200". */
+export declare function numbersIn(normalized: string): string[];
+/** Every number written in `value` also appears in the quote: a claim can't carry a figure its source doesn't. */
+export declare function numbersGrounded(value: unknown, quote: unknown): boolean;
+/**
+ * House style: no em or en dashes in anything a person reads. Takes them out
+ * of generated copy and stored values.
+ *
+ * - A range keeps a hyphen: a number range ("3-4 beds"), a price range
+ *   ("$2,000 - $9,000"), a time range ("9:00 AM - 6:00 PM"), and an unspaced
+ *   en dash between words ("Mon-Fri").
+ * - Any other em or en dash between words becomes a comma ("great light, call
+ *   me").
+ *
+ * Never run a verbatim quote through this: a quote stays as it was written.
+ */
+export declare function removeDashes(text: string): string;
+/** Whether a sentence reads as a note about how the copy was written (its instructions or evidence), not copy for the reader. */
+export declare function isWriterNote(text: unknown): boolean;
+export type OutboundFormat = 'html' | 'text';
+export type OutboundChannel = 'email' | 'sms';
+/**
+ * The text a reader sees in an email body, one line per block.
+ *
+ * - html: scripts, styles and comments dropped; source whitespace collapsed;
+ *   a line break at br, p, li, div, headings, rows and other blocks; a link
+ *   `<a href="u">t</a>` as "t (u)" unless t is the address itself; an
+ *   image's alt and title text, and any other element's title, on their own
+ *   line; inline tags removed without a space (so "guaran<b></b>teed" is one
+ *   word); entities decoded once; spaces collapsed and empty lines dropped.
+ * - text: entities decoded once, nothing else.
+ */
+export declare function outboundPlainText(body: unknown, format: OutboundFormat): string;
+/**
+ * Who wrote the copy, stamped once when the row is created
+ * (payload.claim_author) and never derived from who filed it:
+ *  - signal: Signal's own generators, however they were asked;
+ *  - agent: an MCP agent's own words;
+ *  - operator: a fixed template or a person's own copy.
+ */
+export type OutboundAuthor = 'signal' | 'agent' | 'operator';
+export declare const OUTBOUND_AUTHORS: ReadonlyArray<OutboundAuthor>;
+/** Refused outright (400 outbound_copy_refused), at filing and again at send. */
+export type OutboundBlockCode = 'empty_subject' | 'empty_body' | 'unrendered_token' | 'platform_banned_claim' | 'project_banned_claim' | 'forbidden_phrase' | 'price_mismatch' | 'mixed_script' | 'dash' | 'unsafe_markup' | 'prompt_control_token';
+/** Needs a person's look (or, for an agent's own copy, is reported back): forces propose. */
+export type OutboundFlagCode = 'price_unverifiable' | 'unsupported_number' | 'citation_invalid' | 'citation_mismatch' | 'citation_wrong_source' | 'banned_claim_negated' | 'writer_note' | 'number_from_research' | 'audit_flag' | 'audit_not_run';
+/** House style. Never blocks and never forces propose. */
+export type OutboundStyleCode = 'uncontracted' | 'dash' | 'first_person_firm';
+export type OutboundFindingCode = OutboundBlockCode | OutboundFlagCode | OutboundStyleCode;
+export interface OutboundFinding {
+    /** Stable: FNV-1a of the code, the normalized sentence and the normalized match. A new sentence is a new id. */
+    id: string;
+    code: OutboundFindingCode;
+    /** The sentence as the reader sees it (entities decoded). */
+    sentence: string;
+    /** What matched, as normalized for matching. */
+    match: string;
+    reason: string;
+    fix: string;
+    /** The Business Brief fact a citation finding is about. */
+    fact_id?: string;
+}
+/**
+ * FNV-1a (32-bit) of a string's UTF-16 code units, as 8 lowercase hex digits.
+ * The one hash the contracts use for finding ids and fingerprints.
+ */
+export declare function fnv1a(text: string): string;
+/** A finding's id: the same code, sentence and match always give the same id, anywhere. */
+export declare function outboundFindingId(code: string, sentence: string, match: string): string;
+/**
+ * Build a finding with its stable id. Signal's gate uses it for the findings
+ * only it can make (prompt_control_token, audit_flag, audit_not_run), so
+ * every finding's id is computed one way.
+ */
+export declare function makeOutboundFinding(code: OutboundFindingCode, sentence: string, match: string, extra?: {
+    reason?: string;
+    fix?: string;
+    fact_id?: string;
+}): OutboundFinding;
+export type PlatformBannedClaimId = 'guaranteed_ranking' | 'number_one_on_google' | 'guaranteed_results' | 'hundred_percent_guaranteed' | 'risk_free' | 'fake_scarcity' | 'google_endorsed' | 'pay_nothing_guarantee';
+/** Claims no outbound copy may make, for any business. Generic on purpose: a project adds its own in its Business Brief. */
+export declare const PLATFORM_BANNED_CLAIMS: ReadonlyArray<{
+    id: PlatformBannedClaimId;
+    description: string;
+}>;
+export interface PlatformClaimHit {
+    id: PlatformBannedClaimId;
+    /** Offset into the normalized text. */
+    index: number;
+    match: string;
+    /** True when a negation directly governing its guarantee or promise takes it back ("We can't guarantee rankings"). */
+    negated: boolean;
+}
+/**
+ * Every PLATFORM_BANNED_CLAIMS hit in a text. A negation suppresses a hit
+ * only when it directly governs the guarantee or promise ("can't
+ * guarantee", "no one can promise"), or the verb a hit starts with ("we
+ * can't get you to the top of Google", "not endorsed by Google"); "not
+ * only", "no other", "don't settle", "don't wait" and "don't miss" never do.
+ * A suppressed hit comes back with `negated: true`: still worth a person's
+ * look. A #1 or top-of-Google hit needs a verb that puts someone there, so
+ * an observation ("you're near the top of Google") isn't one.
+ */
+export declare function findPlatformBannedClaims(text: unknown): PlatformClaimHit[];
+export interface PhraseHit {
+    /** The phrase as you passed it. */
+    phrase: string;
+    /** Offset into the normalized text. */
+    index: number;
+    /** The phrase as normalized. */
+    match: string;
+}
+/**
+ * Literal phrases found as whole spans, case-insensitive, after both sides
+ * are normalized (entities, invisible characters, quotes and dashes). The one
+ * matcher for a project's banned claims and a narrative's forbidden phrases.
+ */
+export declare function findPhrases(text: unknown, phrases: ReadonlyArray<unknown> | null | undefined): PhraseHit[];
+export interface SpanHit {
+    /** Offset into the text the finder read (normalized for findUnrenderedTokens, as given otherwise). */
+    index: number;
+    match: string;
+}
+/**
+ * Template text that never got filled in: {{x}}, {%x%}, [[x]], %TOKEN%,
+ * ${x}, {x}, unresolved {a|b} spintax, a bracketed name or company
+ * placeholder ("[First Name]"), a greeting to undefined or null, and
+ * "[object Object]". Reads the normalized text.
+ */
+export declare function findUnrenderedTokens(text: unknown): SpanHit[];
+/**
+ * Dashes the house voice never uses: an em dash anywhere, and an en dash
+ * between words. An en dash inside a number, time or $ range ("3–4",
+ * "9:00 AM – 6:00 PM", "$2,000 – $9,000") or unspaced between two
+ * words ("Mon–Fri") is a range, and a hyphen is never a dash. Reads the
+ * text as given (decode entities first), so it can tell the dashes apart.
+ */
+export declare function findDashes(text: unknown): Array<SpanHit & {
+    kind: 'em' | 'en';
+}>;
+/**
+ * Words that mix Latin letters with Cyrillic or Greek ones ("Gооgle"
+ * with two Cyrillic o's), which only look like ordinary words. A word that's
+ * all Cyrillic or all Greek is left alone.
+ */
+export declare function findMixedScript(text: unknown): SpanHit[];
+/**
+ * Markup an agent's HTML email may not carry: <style>, <script>, on*=
+ * event handlers, CSS content: in a style attribute, embedded frames or
+ * objects, and javascript: links. Reads the HTML as written.
+ */
+export declare function findUnsafeMarkup(html: unknown): SpanHit[];
+export type PriceShape = 'exact' | 'floor' | 'ceiling' | 'range';
+export interface PriceMention {
+    /** Offset into the normalized text. */
+    index: number;
+    /** The whole mention, floor or ceiling words and the range included ("starting at $4,000", "$4,000-$15,000"). */
+    match: string;
+    shape: PriceShape;
+    min: number;
+    max: number;
+    /** The dollar amounts in it, as written. */
+    amounts: string[];
+}
+/**
+ * Every price in a text, with its shape: exact ("$4,500"), a floor
+ * ("starting at $4,000", "$25,000+"), a ceiling ("up to $900") or a range
+ * ("$4,000 - $15,000", "between $4k and $15k"). Reads the normalized text.
+ */
+export declare function findPriceMentions(text: unknown): PriceMention[];
+export interface ClaimNumber {
+    /** Offset into the normalized text. */
+    index: number;
+    /** The number as written, with its % or x ("45%", "3x", "120", "$300"). */
+    match: string;
+    /** Its digits, commas dropped ("1200", "4.9"): what grounding compares. */
+    value: string;
+    kind: 'percent' | 'multiplier' | 'count' | 'money';
+}
+/**
+ * The claim numbers in a text (see ClaimNumber) that none of `sources`
+ * carries. Times, dates, phones, years, addresses and the digits of a web or
+ * email address aren't claims and are skipped. Reads the normalized text.
+ */
+export declare function findUnsupportedNumbers(text: unknown, sources?: ReadonlyArray<unknown>): ClaimNumber[];
+export type ClaimSubject = 'sender' | 'recipient' | 'unknown';
+/**
+ * Whose claim the number at `index` is: the nearest pronoun or name before
+ * it in the same clause (a clause ends at , ; : or a dash, and at "and" or
+ * "but"). We, our, us (and I, me, my) and the sender's names mean the sender;
+ * you, your and the recipient's names mean the recipient. A bare I or we
+ * followed by an observation verb ("I noticed", "we measured") names neither.
+ * 'unknown' when the clause names neither: a caller treats that as the
+ * sender's unless the number is in the research about the recipient.
+ */
+export declare function claimSubjectOf(sentence: string, index: number, names?: {
+    senderNames?: ReadonlyArray<string> | null;
+    recipientNames?: ReadonlyArray<string> | null;
+}): ClaimSubject;
+/**
+ * "I" with the firm's work: build, built, design, offer, work with, put
+ * together, deliver ("I built your competitor's site"). The firm's work is
+ * "we"; "I" is for what the sender noticed, read or thinks. Quotes are left
+ * alone.
+ */
+export declare function findFirstPersonFirm(text: unknown): SpanHit[];
+/** A claim the writer made and what backs it: a Business Brief fact, or the research about the recipient. */
+export type OutboundClaim = {
+    text: string;
+    fact_id?: string | null;
+} | {
+    text: string;
+    evidence: 'research';
+};
+/** A price as the Business Brief publishes it ("$4,000 - $15,000", "Starting at $500 a month"). */
+export interface OutboundPrice {
+    display: string;
+    fact_id?: string | null;
+}
+/** A Business Brief fact a claim may cite by id. Only a verified one supports anything. */
+export interface OutboundFact {
+    id: string;
+    text: string;
+    verified: boolean;
+}
+/**
+ * The project's rules, pre-resolved by the caller from its Business Brief and
+ * narrative, so no brain shape lives here. Frozen into a review, they're what
+ * the send side re-checks the BLOCK set against.
+ */
+export interface OutboundRules {
+    /** Published prices. */
+    prices: ReadonlyArray<OutboundPrice>;
+    /** True once the brief publishes a price: then a $ amount that matches none of them is refused, not flagged. */
+    prices_known: boolean;
+    /** The project's banned claims, matched literally. */
+    banned: ReadonlyArray<string>;
+    /** The narrative's forbidden phrases, matched literally. */
+    forbidden: ReadonlyArray<string>;
+    facts?: ReadonlyArray<OutboundFact>;
+    /** The business's own names, for telling a claim about the sender from one about the recipient. */
+    sender_names?: ReadonlyArray<string>;
+}
+export interface OutboundCopy {
+    subject?: string | null;
+    body: string;
+    format: OutboundFormat;
+    channel: OutboundChannel;
+}
+export interface OutboundEvidence {
+    /** Primary evidence about the recipient (their homepage text, measured scores). The only research that grounds anything. */
+    primary?: string | null;
+    /** Earlier guesses (a cached model audit). Never grounds a claim; for the model audit's fence only. */
+    hints?: string | null;
+}
+export interface OutboundCheckContext {
+    author: OutboundAuthor;
+    /** Price, banned and forbidden rules run only when set. */
+    rules?: OutboundRules | null;
+    claims?: ReadonlyArray<OutboundClaim> | null;
+    evidence?: OutboundEvidence | null;
+    /**
+     * cited: a number must be backed by a claim the writer cited (Signal's copy).
+     * present: a number may also be backed by a verified fact or the primary
+     * evidence that carries it (an agent's own copy). Defaults to present for
+     * an agent and cited otherwise.
+     */
+    numbers?: 'cited' | 'present';
+    recipient?: {
+        names?: ReadonlyArray<string> | null;
+    } | null;
+}
+export interface OutboundCheck {
+    /** Refused at filing and again at send. */
+    blocking: OutboundFinding[];
+    /** Forces propose; a person settles them (an agent's own are reported back). Always empty for operator copy. */
+    flags: OutboundFinding[];
+    /** House style. Never blocks. */
+    style: OutboundFinding[];
+    /** The body as the reader sees it (outboundPlainText). */
+    plain: string;
+}
+/**
+ * The one outbound checker. Reads the copy as the reader sees it
+ * (outboundPlainText, then normalized for matching, entities decoded once),
+ * sentence by sentence, and sorts what it finds into:
+ *
+ * - blocking: empty subject (email), empty body (fewer than 8 letters in an
+ *   email, none in a text), unrendered tokens, platform banned claims, the
+ *   project's banned claims and the narrative's forbidden phrases, a price
+ *   that matches no published one (once prices are known), mixed-script
+ *   words, and for an agent's own copy dashes and unsafe HTML markup.
+ * - flags (never for operator copy): unverifiable prices, unsupported
+ *   numbers, citations that are unknown, unverified, don't match or come
+ *   from the wrong source, a banned claim a negation takes back, writer
+ *   notes, and for an agent's own copy numbers taken from the research.
+ * - style: uncontracted forms, dashes (Signal and operator copy) and "I" for
+ *   the firm's work.
+ *
+ * Research grounds a number or a price only in a sentence about the
+ * recipient (claimSubjectOf); in a sentence about the sender it's
+ * citation_wrong_source. A clause that names nobody counts as the
+ * recipient's only when the research about them carries that number, and a
+ * subject line may repeat a number the body cites that way. Price rules run
+ * only when ctx.rules is set. An author it doesn't know is checked as an
+ * agent, the strictest set.
+ */
+export declare function checkOutboundCopy(copy: OutboundCopy, ctx: OutboundCheckContext): OutboundCheck;
+export declare const OUTBOUND_AUDIT_STATUSES: readonly ['clean', 'flagged', 'not_run', 'not_needed', 'stale'];
+export type OutboundAuditStatus = (typeof OUTBOUND_AUDIT_STATUSES)[number];
+export interface OutboundClaimAudit {
+    status: OutboundAuditStatus;
+    [key: string]: unknown;
+}
+/** A person said they checked these flags, at approval. */
+export interface OutboundAcknowledgement {
+    by: string;
+    at: string;
+    /** The route it came through ('dashboard', 'drafts', ...). */
+    via: string;
+    flag_ids: string[];
+}
+/** An MCP agent stood behind the flags on its own copy. An assertion, never a review: it settles flags only on author agent copy. */
+export interface OutboundAssertion {
+    by: string;
+    at: string;
+    flag_ids: string[];
+}
+/** payload.claim_review: what the checker and the audit found when the copy was filed, and who settled it. */
+export interface OutboundClaimReview {
+    version: 1;
+    checked_at: string;
+    author: OutboundAuthor;
+    brain_version: number | null;
+    /** The rules the copy was checked against, frozen, so the send side re-checks the same ones. */
+    rules: OutboundRules | null;
+    flags: OutboundFinding[];
+    style: OutboundFinding[];
+    audit: OutboundClaimAudit;
+    acknowledged: OutboundAcknowledgement | null;
+    asserted: OutboundAssertion | null;
+}
+/**
+ * A stored claim review, read strictly. Null means not reviewed: missing,
+ * from another version, or malformed anywhere (a caller treats a malformed
+ * review exactly like a missing one, never as a clean one).
+ */
+export declare function readOutboundClaimReview(value: unknown): OutboundClaimReview | null;
+/**
+ * The flags nobody has settled: in neither acknowledged.flag_ids (a person,
+ * at approval) nor, on an agent's own copy only, asserted.flag_ids (the agent
+ * standing behind them). Empty means it may go out.
+ */
+export declare function unsettledFlags(review: OutboundClaimReview): OutboundFinding[];
+/**
+ * The one wording for a refusal: every fix, numbered, each with the sentence
+ * it's about. Contracted, and never an em or en dash (one in a quoted
+ * sentence is spelled out as "[em dash]").
+ */
+export declare function outboundRefusalMessage(findings: ReadonlyArray<Pick<OutboundFinding, 'sentence' | 'reason' | 'fix'>>): string;
+export type ReadBackStatus = 'verified' | 'empty' | 'mismatch' | 'unreadable';
+export interface ReadBackVerdict {
+    status: ReadBackStatus;
+    /** Length of what was read, normalized. */
+    body_chars: number;
+    /** Length of what was meant to go out, normalized. */
+    intended_chars: number;
+    /** How much of the intended text, from the first character it stops matching, isn't there. 0 when verified. */
+    chars_missing: number;
+    /** Links in the intended copy that aren't in what was read. */
+    urls_missing: string[];
+}
+/** A body to compare: a string (read as HTML when it has a tag), or the body with its format. */
+export type ReadBackBody = string | {
+    body: string | null | undefined;
+    format?: OutboundFormat;
+};
+/**
+ * Whether what a mailbox says it sent is what was meant to go out. Both sides
+ * are read as the reader sees them and normalized, so markup, entities,
+ * quotes and whitespace don't count.
+ *
+ * - verified: the whole intended text is in what was read (a footer or a
+ *   quoted header around it is fine), and so is every link it carries.
+ * - empty: what was read has fewer than 8 letters.
+ * - mismatch: anything else, with how much of the intended text is missing
+ *   (from the first point it stops matching) and which links are.
+ * - unreadable: nothing could be read.
+ */
+export declare function readBackVerdict(intended: ReadBackBody, read: ReadBackBody | null | undefined): ReadBackVerdict;