@sonordev/contracts 2.7.1 → 2.9.0

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;