@sonordev/contracts 2.13.0 → 2.16.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2.16.0
+
+A minor release: `@sonordev/contracts/portfolio` gains the verification, a proof-stage section for builds a Lighthouse run can't honestly score. Every other entry is unchanged. Nothing was removed or renamed, but three things behave differently. `PortfolioSectionType` has a new member, so a `Record<PortfolioSectionType, ...>` you keep needs an entry for `portfolioVerification` before it type-checks. `caseStudyStageStatus` reads each section's `data`. A reported number's date has to be a real day.
+
+- **A new section type, `portfolioVerification`.** An app behind a sign-in has a public door and little else a browser can reach, and a Lighthouse score for the door reads as a score for the app. A verification is a short list of checks instead (one to eight). Each says what it's called (`label`), what came out (`result`), what was measured (`measured`), where (`where`: a URL, a screen or a file), with which tool and settings (`method`), on what day (`date`, YYYY-MM-DD) and, required, what it doesn't cover (`scope`). A check that can't state its limits isn't a check. Every check is something you ran yourself; a figure a client gave you stays a reported number in Results.
+- **It sits in the proof stage**, after `portfolioPerformance` and `portfolioSpeedComparison`. `PORTFOLIO_SECTION_TYPES` grows by one entry, so the `PORTFOLIO_SECTION_ORDER` value of each outcome section and the CTA rises by one. The reading order itself is unchanged.
+- **It completes the proof stage on its own, once it has something to show.** `caseStudyStageStatus` counts a verification toward the proof stage only when its `data` holds at least one check a page may show (`readVerificationChecks`). An empty verification, which is what an editor's Add button creates, leaves the stage incomplete and says so, instead of reading as a finished proof stage over an empty one. `SectionLike` gains an optional `data`; pass each section's `data`, because a caller that passes only `sectionType` sees a verification as empty. `STAGE_CORE_SECTION` still names Performance as the section to offer when a stage is empty; `STAGE_CORE_ALTERNATES` lists the sections that stand in for a stage's core and `stageCoreSections(stage)` returns the core and its stand-ins together. Nothing is gated on the kind of project, because the status doesn't know it. An empty proof stage now says a verification is the other way to fill it.
+- **One rule for what a day is.** `isRealDay(value)` says whether a string is a real calendar day written YYYY-MM-DD. A verification's `date` and a reported number's `reportedBy.date` both ask it. The reported number's date used to go through `Date.parse`, which rolls `2026-02-31` into March and let it pass; it's now refused, so a number can't be attributed to a day that doesn't exist.
+- **Validating and reading one.** `PortfolioVerificationData` and `VerificationCheck` are the shapes. `verificationProblems(data, { latestDay? })` lists what's wrong, one sentence each, with the check's position: a missing field, a field over its limit (`VERIFICATION_FIELD_MAX_CHARS`) or not one line of plain text (a control character, a zero-width or direction mark), more than `VERIFICATION_MAX_CHECKS` checks, a day that doesn't exist, a day before `VERIFICATION_EARLIEST_DAY` or after `latestVerificationDay()` (tomorrow in UTC, so a check run today in any time zone passes and one that hasn't happened doesn't; `readVerificationChecks` applies the same bound), a `where` that says nothing ("n/a", one plain word), carries a username or password, or names localhost or a private network, a field the check doesn't have, and a scope that doesn't state a limit (`isVacuousScope`): it has to be a sentence with a word that marks where coverage stops, such as "only", "not" or "without", so placeholders ("N/A", "None at all"), coverage claims ("All screens") and denied limits ("No restrictions") are refused. It reads English, and it can see that a limit was written, not that it's true, so a person still reads the scope. `isPlaceholderText(text)` is the test for a line with nothing in it ("n/a", "see above"), shared by `where` and `scope`. `readVerificationChecks(data)` returns the checks that can be shown, trimmed and in order, and leaves out any that fail, so a check with no scope line, or a placeholder for one, doesn't print. `verificationLink(where)` returns a plain `http` or `https` address with a public host as a link and everything else, localhost included, as null. `PORTFOLIO_VERIFICATION_JSON_SCHEMA` is the same shape as a schema.
+
+## 2.15.0
+
+- `llms` holds the rules for what llms.txt says about each page, so the Sonor API and site-kit's local generator build page lines the same way. New: `pickLlmsPageDescription` and `resolveLlmsPageDescription` (summary, curated meta, served meta, schema description, then a cleaned scrape), `llmsPageListNote`, `llmsPageTitle`, `isLlmsListablePage`, `selectLlmsPages`, `groupLlmsPages`, `llmsBlockquoteSummary`, `llmsContactLines`, `llmsAbsoluteUrl`, `cleanScrapedPageText`, `stripContactDetails`, `stripPageFiller` and `LLMS_DESCRIPTION_MAX_LENGTH`.
+- `sanitizeLlmsPublicSummary` removes a phone number or email address, with the "call" or "email us at" in front of it, and a "This page covers" lead-in, and keeps the rest. It used to return `null` for any summary that mentioned a phone or email, and a page with no summary is described by its scrape.
+
+- Add `@sonordev/contracts/funnels` with bounded incomplete drafts, launch-ready definitions, command envelopes, brand presentation overrides, readiness and public page validation. Runtime parsers and JSON schemas share the same shapes.
+- Add the canonical funnel content cache tag and campaign normalization used by managed landing pages. Existing publication logo roles and inbox behavior remain available.
+
+## 2.14.0
+
+- Publication branding adds optional `identity.squareLogoUrl` and `identity.fullLogoUrl` for a square publication mark and its full/display logo. Both use the existing URL validation and support `null` in patches to clear an override. Theme variants in `identity.logos`, the text `identity.wordmark`, and publisher attribution remain separate. Existing saved profiles keep their shape and version.
+- Add `@sonordev/contracts/inbox`: the one rule for which inbox cards are decisions that "Mark all read" and "Dismiss all" leave alone. `isDecisionCard(card)` counts an approval, the ledger's unconfirmed-action card and any card carrying a proposal; `DECISION_INSIGHT_TYPES`, `APPROVAL_NEEDED_INSIGHT_TYPE` and `LEDGER_UNCONFIRMED_INSIGHT_TYPE` are the types behind it. The Signal API and the dashboard read the same rule, so a bulk action's preview matches what it writes.
+
 ## 2.13.0
 
 - Publication branding adds `editorial.focusClosingBackground`, with `planned_photo` and `article_atmosphere` choices. The setting inherits through publication and platform layers, and supports clearing an override. Article atmosphere closing frames reuse saved artwork and the real author portrait; other publications retain their existing behavior.

package/README.md

@@ -18,14 +18,14 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/sites` | The canonical shape of a site host (the multi-site `site` dimension) | every ingest and read that filters by site |
 | `@sonordev/contracts/seo-pages` | Which `seo_pages` row a path resolves to on a multi-site project | the Sonor API, Signal, site-kit's sitemap sync |
 | `@sonordev/contracts/seo-meta` | Whether a title or description is fit to ship | site-kit, Signal's SEO gate |
-| `@sonordev/contracts/llms` | llms.txt sanitizers, the word-safe cut they use (`clipAtWordBoundary`), and the contract version | site-kit, the Sonor API, Signal's schema validation |
+| `@sonordev/contracts/llms` | llms.txt sanitizers, the word-safe cut they use (`clipAtWordBoundary`), what each page line says (`pickLlmsPageDescription`: summary, curated meta, served meta, schema description, then a cleaned scrape; `llmsPageTitle`, `isLlmsListablePage`, `groupLlmsPages`, `selectLlmsPages`) and the contract version | site-kit, the Sonor API, Signal's schema validation |
 | `@sonordev/contracts/forms` | The honeypot policy | site-kit forms, the Sonor API's form intake |
 | `@sonordev/contracts/fleet` | The fleet heartbeat's wire shape | site-kit, the Sonor API |
 | `@sonordev/contracts/slots` | Slot payload signing, contract v2 (HMAC; Node only). Signs and verifies v1 for older site-kit releases | the Sonor API, site-kit on the server |
 | `@sonordev/contracts/slot-content` | What a slot of each kind may hold (`normalizeSlotValue`), safe links, the rich-text parser. No `crypto`, so browsers can import it | the Sonor API, site-kit, the dashboard editor |
 | `@sonordev/contracts/site-cache` | The cache tags a site's Sonor fetches carry and the revalidation route's path, payload and ping | site-kit tags and serves the route, the Sonor API calls it |
 | `@sonordev/contracts/site-edit` | Edit on page: the messages between a framed site and the dashboard, trusted origins, how a slot is found on the page | site-kit's overlay, the dashboard's visual editor |
-| `@sonordev/contracts/portfolio` | The case study arc: every section type, the stage each belongs to, the reading order, the narrative that opens each stage and the thread from a challenge to the phase that cleared it and the result that proves it. Also where a portfolio number comes from and which may headline, and the live-frame message | the Sonor API, Signal's case-study writer, the dashboard's editor, agency-site-kit |
+| `@sonordev/contracts/portfolio` | The case study arc: every section type, the stage each belongs to, the reading order, the narrative that opens each stage and the thread from a challenge to the phase that cleared it and the result that proves it. The verification, the proof for a build a Lighthouse run can't score: checks that each state what they don't cover. Also where a portfolio number comes from and which may headline, and the live-frame message | the Sonor API, Signal's case-study writer, the dashboard's editor, agency-site-kit |
 | `@sonordev/contracts/proposal-sitemap` | How a proposal's site plan counts its pages, when its before-and-after comparison may show, and whether the page counts stated elsewhere in the proposal add up | the Sonor API, Signal's proposal writer, the dashboard's proposal pages |
 | `@sonordev/contracts/voice` | The house voice's contraction rule. `findUncontracted` and `contractText` find and apply full forms that should be contractions; `findContracted` finds the contractions a question-form heading should expand | anything that checks or rewrites copy: Sonor's APIs and dashboard |
 | `@sonordev/contracts/error-page` | Whether stored text is a rendered error page rather than a page's content, and whether generated copy says the page itself is missing | anything that stores page text or writes page copy from it: the Sonor API's page-view and sitemap writers, Signal's metadata generators |
@@ -38,6 +38,8 @@ pnpm add @sonordev/contracts
 | `@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 |
 | `@sonordev/contracts/public-url-host` | Which literal hosts are refused as public fetch destinations (`isBlockedPublicUrlHost`) | the Sonor API and Signal's URL validators and network fetchers |
+| `@sonordev/contracts/funnels` | Incomplete drafts, launch definitions, command/readiness/receipt schemas, bounded public pages and presentation-only brand overrides | Sites, APIs, UI and agent adapters share the same rules |
+| `@sonordev/contracts/inbox` | Which inbox cards are decisions a bulk action leaves alone (`isDecisionCard`, `DECISION_INSIGHT_TYPES`) | Signal's inbox decides what "Mark all read" and "Dismiss all" may touch, the dashboard previews the same result before the write |
 
 ## Focus closing artwork
 
@@ -63,6 +65,31 @@ isn't proof a destination is public: the fetcher still validates the protocol,
 credentials and port, checks the DNS addresses it connects to, and applies its
 redirect policy on each hop. Those network protections stay in the APIs.
 
+## Inbox decisions
+
+"Mark all read" and "Dismiss all" never touch a decision, so clearing a backlog
+of notices can't bury an approval waiting on a yes. `isDecisionCard(card)` is
+that rule: the Signal API follows it when it writes, and the dashboard follows
+it to show the result before the write, so the two can't drift apart.
+
+A card is a decision when it is:
+
+- an approval (insight type `approval_needed`, `APPROVAL_NEEDED_INSIGHT_TYPE`);
+- the ledger's unconfirmed-action card (`ledger_unconfirmed_action`,
+  `LEDGER_UNCONFIRMED_INSIGHT_TYPE`): Signal started something it never saw
+  finish, so a person has to check it. It's raised once per claim, so a bulk
+  dismissal that took it would leave nobody told. It carries no proposal, so
+  there's nothing to approve or reject on it; or
+- any card carrying a ledger proposal (`data.proposal_id` set).
+
+`DECISION_INSIGHT_TYPES` is the first two, for the callers that need them as a
+list (a database filter that leaves them out of a bulk write, for one).
+`isDecisionCard` takes any object with an `insight_type` string and an optional
+`data` object, so a stored row and the dashboard's inbox item both fit. It reads
+`data.proposal_id` the way the database reads `data->>proposal_id`: a missing
+key, a JSON `null` and a `null` `data` mean no proposal, and any other value,
+an empty string included, means one.
+
 ## Schema placeholders
 
 `schema-placeholders` finds the parts of a JSON-LD value that a template left
@@ -794,6 +821,14 @@ branding.mergePublicationBrandingPatch(saved, { identity: { logos: { dark: null
   `{ version: 1 }`, and a change that sets nothing returns the profile as it
   was. **`mergePublicationBrandingLayers`** is the same leaf-wise merge for
   resolving layers.
+- **Publication logo roles** are optional `identity.squareLogoUrl` and
+  `identity.fullLogoUrl`. Use the first for a square publication mark and the
+  second for its full/display logo. Both follow the same URL policy as other
+  logo fields. Set either leaf to `null` in a patch to clear that override
+  and restore inheritance. `identity.logos.default/light/dark` remain theme
+  variants, `identity.wordmark` stays text, and `publisherLogoUrl` is publisher
+  attribution. Omitting the new leaves preserves existing profiles; the
+  validator doesn't infer a square mark or select an effective display logo.
 - **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
@@ -836,8 +871,12 @@ the dashboard that edits it and every site that renders it.
   with its sections; a stage with nothing in it is left out.
 - **`caseStudyStageStatus(sections)`** reports all four stages, complete
   only when the stage's core section (`STAGE_CORE_SECTION`: challenges,
-  strategy, performance, results) is present, with one sentence on what's
-  missing. The dashboard shows it beside the editor.
+  strategy, performance, results) or a stand-in for it
+  (`STAGE_CORE_ALTERNATES`: a verification completes the proof stage) is
+  present, with one sentence on what's missing. A stand-in counts only when
+  its `data` holds something a page can show, so pass each section's `data`
+  along with its `sectionType`. `stageCoreSections(stage)` lists the core and
+  its stand-ins. The dashboard shows the status beside the editor.
 - **Stage names.** The ids are fixed; what people see isn't. A site names
   the four stages in the dashboard ("Heat", "Shape", "Temper", "Finish"),
   per project like the rest of its branding, and `CaseStudyStageNames`
@@ -856,6 +895,100 @@ the dashboard that edits it and every site that renders it.
   phases, results })` names every challenge nothing resolves or proves and
   every dangling reference. It judges links only where ids were written, so
   content from before the thread passes.
+- **`isRealDay(value)`** is the one rule for whether a string is a day: a real
+  calendar day written YYYY-MM-DD. `2026-02-31` isn't one, and neither is a
+  year under 100. A verification's `date` and a reported number's
+  `reportedBy.date` both ask it, and so can anything else that stores a day.
+
+### The verification
+
+A Lighthouse run can only score what a browser reaches without signing in. For
+an app whose screens sit behind a login, that's the sign-in page, and a score
+for the door reads as a score for the app. The `portfolioVerification` section
+is the proof stage for that build: a short list of checks (one to
+`VERIFICATION_MAX_CHECKS`, eight), each stating what it covers and, required,
+what it doesn't.
+
+```ts
+import {
+  readVerificationChecks,
+  verificationLink,
+  verificationProblems,
+  type PortfolioVerificationData,
+} from '@sonordev/contracts/portfolio'
+
+const data: PortfolioVerificationData = {
+  checks: [
+    {
+      label: 'Sign-in page, mobile speed',
+      result: 'Performance 89',
+      measured: 'The Lighthouse performance score of the page a visitor sees before signing in',
+      where: 'https://example.com/login',
+      method: 'Lighthouse 13, mobile preset, median of 3 runs',
+      date: '2026-10-20',
+      scope: 'The sign-in page only; the screens behind it were not measured.',
+    },
+  ],
+}
+
+verificationProblems(data) // []
+readVerificationChecks(data) // the checks a page may print
+verificationLink(data.checks[0].where) // 'https://example.com/login'
+```
+
+- **Every field is required**, and each is one line of plain text within its
+  limit (`VERIFICATION_FIELD_MAX_CHARS`): no line break, tab or other control
+  character, and no zero-width or direction mark. `date` is a real day, YYYY-MM-DD, no
+  earlier than `VERIFICATION_EARLIEST_DAY` (2000-01-01) and no later than
+  `latestVerificationDay()`, which is tomorrow in UTC. That lets a check run
+  today in a time zone ahead of your server through and refuses one that hasn't
+  happened. `verificationProblems` and `readVerificationChecks` both apply it
+  without being asked; pass `{ latestDay }` to fix the clock.
+- **`where` points somewhere a reader can go or look.** A public web address,
+  or a screen or file named in words ("the migrations in the repository") or as
+  a path. A placeholder ("n/a", "here"; `isPlaceholderText` is the test), one
+  plain word, a username or password
+  in an address, and localhost or a private network are refused. One thing no
+  rule can catch is a view link with a token in its path or query: if the link
+  works for whoever holds it, don't put it here.
+- **`scope` states a limit.** It's what the check does _not_ cover, written as a
+  sentence with a word that marks where coverage stops: "only", "not", "except",
+  "without", or a contraction like "weren't". A placeholder ("N/A", "none",
+  "TBD"), a coverage claim ("All screens", "Fully tested") and a denied limit
+  ("No restrictions") are refused (`isVacuousScope`). "Desktop only" and
+  "Counted, not exercised" pass. Write what the check leaves out: "Counted from
+  the migrations; no query ran as a signed-in user." The test reads English, and
+  it can see that a limit was written, not that it's true, so a person still
+  reads the scope before a case study goes live.
+- **`verificationProblems(data, options)`** names every problem with the check's
+  position (`checks[1].scope is required: say what the check does not cover`),
+  and refuses a field a check doesn't have. Whatever stores a verification
+  should run it first. Nothing calls it for you, and until a write path does,
+  stored data can hold anything, which is why `readVerificationChecks` checks
+  again before a page prints.
+- **`readVerificationChecks(data)`** is what a page prints: the checks that pass,
+  trimmed and in order, up to the limit. A check that fails is left out, so one
+  with no scope line, or a placeholder for one, doesn't print, and a field a
+  newer writer added is ignored.
+- **`verificationLink(where)`** returns the address when `where` is exactly one
+  `http` or `https` URL with no credentials in it and a public host, and null
+  for a screen name, a file path, localhost or anything else, so only a real
+  public address becomes a link.
+- **Every check is something you ran.** There's no `source` on a check. A figure
+  the client gave you stays in Results as a reported number, with the person
+  behind it.
+- **`PORTFOLIO_VERIFICATION_JSON_SCHEMA`** is the same shape for agents. What a
+  `scope` or a `where` says, and whether a `date` is a real day in range, are
+  `verificationProblems`' job; a schema can't express them.
+
+It completes the proof stage on its own (`STAGE_CORE_ALTERNATES`), once it has
+at least one check `readVerificationChecks` would show. An empty verification,
+which is what an editor's Add button creates, leaves the stage incomplete and
+says why; `caseStudyStageStatus` reads that from each section's `data`, and a
+caller that passes only `sectionType` sees a verification as empty. Any project
+can use it. The status doesn't know the kind of project, so nothing is gated on
+it; a site that wants a Lighthouse score for a public site keeps writing a
+Performance section.
 
 ## Why it exists
 
@@ -882,3 +1015,15 @@ a shape bumps the major and that contract's own `*_VERSION` constant.
 ### Editorial media
 
 `@sonordev/contracts/editorial-media` exports `resolveArticlePhotoPlacements(html, photos)`, returning section targets and a status/offset for each explicit placement. Both the editor and article renderer use this contract; a heading with no eligible prose is reported as `no_paragraph`, and missing/ambiguous anchors never drift to another section. `editorialTextId` creates content identities for explicit takeaway assignments. Source-image format, size and completed-art exclusions are shared by the picker and resolver.
+
+## The funnels contract
+
+Import from `@sonordev/contracts/funnels`. `createFunnelDraft(template)` provides neutral defaults for `newsletter`, `requested_guide` and `inquiry`. `parseFunnelDraftDefinition` accepts bounded incomplete drafts so each setup step can save. `parseFunnelDefinition` requires a launch-ready structural definition. Resource ownership, current permission, route installation and launch authorization remain server checks.
+
+Use `parseFunnelCreateArgs`, `parseFunnelUpdateArgs`, `parseFunnelRevisionArgs`, `parseFunnelLaunchArgs`, `parseFunnelLifecycleArgs` and `parseFunnelRetryArgs` at command boundaries. `parseFunnelDraftArgs(value, mode)` requires an explicit create/update mode. Rollback uses `parseFunnelLifecycleArgs(value, 'rollback')`. Matching exported JSON schemas describe the closed structural shapes; runtime parsers also enforce semantic checks such as matching form references and managed paths.
+
+`applyFunnelBrandOverride` takes an already resolved brand, an allowlisted presentation patch and an API-authorized asset map. Null leaves restore inheritance. It returns the resulting brand, overridden field paths and asset references. It doesn't fetch assets, resolve business precedence or calculate authoritative hashes. `parseFunnelBrandSnapshot` validates the captured presentation and provenance.
+
+`parsePublishedFunnelPage` refuses private definition fields and unsafe asset URLs. It supports bounded text paragraphs and bullet lists, with a managed form slug and canonical campaign identity. `managedFunnelPath` reserves `/f/:slug`; a consuming site must opt in and verify its actual routes.
+
+`parseFunnelReadiness`, `parseFunnelOperationReceipt` and the detail/catalog/preview parsers validate bounded response envelopes. Operation receipts bind the exact command target and approved action, and always report zero messages sent by the configuration command. Preview and published-version detail parsers preserve the exact launch or rollback evidence.

package/dist/campaign-normalize.d.ts

@@ -0,0 +1,2 @@
+/** Single source of truth for campaign identities across sites, APIs and funnels. */
+export declare function normalizeCampaignSlug(input?: string | null): string | null;

package/dist/frame-ready.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The live-frame handshake, on its own so it stays small.
+ *
+ * A site-kit page framed by another origin posts FRAME_READY_MESSAGE to its
+ * embedder once it has painted (shared/frame.ts, announceFrameReady); a case
+ * study's device frames (the portfolio renderers) are the ones listening.
+ *
+ * This is a leaf module on purpose. shared/frame.ts runs in every page's
+ * analytics and layout graph, and `./portfolio` is a large module of case
+ * study rules: importing the message from there put all of it in every
+ * page's eager bundle. Single source of truth for the message: `./portfolio`
+ * re-exports it (so `@sonordev/contracts/portfolio` and
+ * `@sonordev/site-kit/portfolio/contract` still carry it) and shared/frame.ts
+ * imports it from here. Keep it free of other imports.
+ */
+/** The message a cross-origin-framed site-kit page posts to its embedder once it has painted. */
+export declare const FRAME_READY_MESSAGE: 'sonor:frame-ready';
+export interface FrameReadyMessage {
+    type: typeof FRAME_READY_MESSAGE;
+    v: 1;
+}
+/** True for a {@link FrameReadyMessage}, for the embedder's message handler. */
+export declare function isFrameReadyMessage(data: unknown): data is FrameReadyMessage;