@sonordev/contracts 2.15.0 → 2.16.0

package/CHANGELOG.md

@@ -1,12 +1,20 @@
 # Changelog
 
-## Unreleased
+## 2.16.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.
+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.
 

package/README.md

@@ -25,7 +25,7 @@ pnpm add @sonordev/contracts
 | `@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 |
@@ -871,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`
@@ -891,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
 

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;

package/dist/portfolio.d.ts

@@ -16,14 +16,7 @@
  * must carry, and which numbers may headline. The Sonor API applies the same
  * rules.
  */
-/** 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;
+export { FRAME_READY_MESSAGE, isFrameReadyMessage, type FrameReadyMessage } from './frame-ready';
 /** Bump on breaking changes to the collapse policy. */
 export declare const PORTFOLIO_CONTRACT_VERSION: 1;
 /** The four beats, in reading order. */
@@ -57,7 +50,7 @@ export declare function stageName(names: CaseStudyStageNames | null | undefined,
  * sections of the story (SEO metadata, the closing CTA). This is THE list;
  * the Sonor API and agency-site-kit import it rather than keeping their own.
  */
-export declare const PORTFOLIO_SECTION_TYPES: readonly ['portfolioHero', 'portfolioChallenges', 'portfolioBeforeAfter', 'portfolioStrategy', 'portfolioSiteArchitecture', 'portfolioDesignSystem', 'portfolioFeatureSpotlight', 'portfolioGallery', 'portfolioVideo', 'portfolioTechStack', 'portfolioPerformance', 'portfolioSpeedComparison', 'portfolioResults', 'portfolioMetricsTimeline', 'portfolioConversionFunnel', 'portfolioServices', 'portfolioTeam', 'portfolioTestimonial', 'portfolioDetails', 'portfolioSeo', 'portfolioCTA'];
+export declare const PORTFOLIO_SECTION_TYPES: readonly ['portfolioHero', 'portfolioChallenges', 'portfolioBeforeAfter', 'portfolioStrategy', 'portfolioSiteArchitecture', 'portfolioDesignSystem', 'portfolioFeatureSpotlight', 'portfolioGallery', 'portfolioVideo', 'portfolioTechStack', 'portfolioPerformance', 'portfolioSpeedComparison', 'portfolioVerification', 'portfolioResults', 'portfolioMetricsTimeline', 'portfolioConversionFunnel', 'portfolioServices', 'portfolioTeam', 'portfolioTestimonial', 'portfolioDetails', 'portfolioSeo', 'portfolioCTA'];
 export type PortfolioSectionType = (typeof PORTFOLIO_SECTION_TYPES)[number];
 export declare function isPortfolioSectionType(value: unknown): value is PortfolioSectionType;
 /**
@@ -70,20 +63,42 @@ export declare const SECTION_STAGE: Record<PortfolioSectionType, CaseStudyStage
 /** The stage a section type belongs to, or null when it sits outside the story. Unknown types are null. */
 export declare function sectionStage(type: string): CaseStudyStage | null;
 /**
- * The one section each stage can't do without. A stage with other sections
- * but not this one is told so by {@link caseStudyStageStatus}: a proof stage
- * that's only a speed comparison has no measurement of the finished build.
+ * The one section each stage can't do without, and the one an editor offers
+ * to add when the stage has nothing. A stage with other sections but not its
+ * core (or a stand-in, {@link STAGE_CORE_ALTERNATES}) is told so by
+ * {@link caseStudyStageStatus}: a proof stage that's only a speed comparison
+ * has no measurement of the finished build.
  */
 export declare const STAGE_CORE_SECTION: Record<CaseStudyStage, PortfolioSectionType>;
+/**
+ * Sections that stand in for a stage's core. A Lighthouse run can only score
+ * what a browser can reach without signing in, so an app whose screens sit
+ * behind a login has no honest Performance section; its proof is a
+ * verification: checks that each say what they cover and what they don't.
+ * Either one completes the proof stage. This is deliberately not gated on
+ * the kind of project: the status below only sees section types, and the
+ * rule for "is this an app" lives with each caller's own data. A verification
+ * is a measurement of the finished build with its limits stated, which is
+ * what the stage asks for. Single source of truth for what completes a stage.
+ */
+export declare const STAGE_CORE_ALTERNATES: Partial<Record<CaseStudyStage, readonly PortfolioSectionType[]>>;
+/** Every section type that completes a stage: its core first, then its stand-ins. */
+export declare function stageCoreSections(stage: CaseStudyStage): PortfolioSectionType[];
 /**
  * Canonical display order, derived from the list above so it can't disagree
  * with the stages. Renderers sort by this when nobody has reordered; the
  * dashboard's stored order only ever moves a section within its stage.
  */
 export declare const PORTFOLIO_SECTION_ORDER: Record<PortfolioSectionType, number>;
-/** The least a section needs for the ordering helpers: its type. Anything else rides along. */
+/**
+ * The least a section needs for the ordering helpers: its type. Anything else
+ * rides along. `data` is optional for them and needed by
+ * {@link caseStudyStageStatus}, which won't count a stand-in section for a
+ * stage's core (a verification) unless its data shows something.
+ */
 export interface SectionLike {
     sectionType: string;
+    data?: unknown;
 }
 /**
  * The sections in the order the case study reads.
@@ -120,7 +135,11 @@ export interface CaseStudyStageStatus {
     stage: CaseStudyStage;
     /** The section types present, in reading order. */
     present: PortfolioSectionType[];
-    /** True when the stage's core section ({@link STAGE_CORE_SECTION}) is present. */
+    /**
+     * True when the stage's core section ({@link STAGE_CORE_SECTION}) is present, or a stand-in for it
+     * ({@link STAGE_CORE_ALTERNATES}) is present with something a page can show. Pass each section's `data`:
+     * a stand-in without it doesn't count.
+     */
     complete: boolean;
     /** Null when complete; otherwise one sentence on what the stage is missing. */
     missing: string | null;
@@ -129,6 +148,10 @@ export interface CaseStudyStageStatus {
  * Each stage's status, all four, in order, whether or not the case study has
  * sections in it. The dashboard shows these beside the editor so an empty
  * proof stage is seen before the case study is published, not after.
+ *
+ * A stage's core section completes it by type. A stand-in for the core (a
+ * verification) completes it only when its `data` holds something a page can
+ * show, so pass `data`; without it a stand-in reads as empty, never as done.
  */
 export declare function caseStudyStageStatus(sections: readonly SectionLike[] | null | undefined): CaseStudyStageStatus[];
 export interface CaseStudyNarrative {
@@ -196,6 +219,166 @@ export declare function caseStudyFlowProblems(input: {
     phases?: readonly PhaseLike[] | null;
     results?: readonly ResultLike[] | null;
 }): string[];
+/**
+ * True for a real calendar day written YYYY-MM-DD. "2026-02-31" is not (Date.parse
+ * rolls it into March), and neither is a year under 100 (Date.UTC maps those into
+ * the 1900s). Single source of truth for what counts as a day.
+ */
+export declare function isRealDay(value: string): boolean;
+/** The most checks one verification lists. It's a short list; the case study isn't an audit report. */
+export declare const VERIFICATION_MAX_CHECKS = 8;
+/** Every field of a check, in the order a renderer reads them. */
+export declare const VERIFICATION_CHECK_FIELDS: readonly ['label', 'result', 'measured', 'where', 'method', 'date', 'scope'];
+export type VerificationCheckField = (typeof VERIFICATION_CHECK_FIELDS)[number];
+/** The longest each text field may run. Each is a line, not a paragraph. `date` is a day, not text. */
+export declare const VERIFICATION_FIELD_MAX_CHARS: {
+    readonly label: 80;
+    readonly result: 120;
+    readonly measured: 200;
+    readonly where: 200;
+    readonly method: 240;
+    readonly scope: 240;
+};
+/** One thing we checked on the finished build. Every field is required. */
+export interface VerificationCheck {
+    /** What the check is called: "Sign-in page, mobile speed". */
+    label: string;
+    /** What came out: "Performance 89", "42 of 42 tables have row-level security". */
+    result: string;
+    /** What was measured: "Lighthouse performance score of the page a visitor sees before signing in". */
+    measured: string;
+    /** Where: a URL, or the screen or file. "https://example.com/login", "the migrations in the repository". */
+    where: string;
+    /** The tool and settings: "Lighthouse 13, mobile preset, median of 3 runs". */
+    method: string;
+    /** The day it was checked, YYYY-MM-DD. */
+    date: string;
+    /** What the check does NOT cover, as a limit: "The sign-in page only; the screens behind it weren't measured." */
+    scope: string;
+}
+/** The `data` of a `portfolioVerification` section. */
+export interface PortfolioVerificationData {
+    checks: VerificationCheck[];
+}
+/** The earliest day a check may carry. An earlier date is a typo, not a check of this build. */
+export declare const VERIFICATION_EARLIEST_DAY = "2000-01-01";
+/**
+ * The latest day a check may carry: tomorrow in UTC. A check run today anywhere
+ * on earth is dated no later than that (the furthest-ahead zone is UTC+14), so a
+ * server's clock can't drop a check dated "today" where the person ran it, and a
+ * date further out is a check that hasn't happened. Single source of truth for
+ * the allowance: writers and readers both use it, so no one keeps a second one.
+ * `now` is for tests and for callers with a clock of their own.
+ */
+export declare function latestVerificationDay(now?: Date): string;
+export interface VerificationOptions {
+    /**
+     * The latest day a check may carry, YYYY-MM-DD; a later one is a problem. Leave it out to use
+     * {@link latestVerificationDay}, which is what a page and a write path both want. Pass one for a fixed clock.
+     */
+    latestDay?: string;
+}
+/**
+ * True when a line says nothing: it has no words, or every word is a
+ * placeholder or filler ("N/A", "n/a n/a", "TBD", "see above", "none at all").
+ */
+export declare function isPlaceholderText(text: string): boolean;
+/**
+ * True when a scope line doesn't state a limit. A scope is "what this check
+ * does NOT cover", so it has to be a sentence that uses a word marking where
+ * coverage stops ("only", "not", "except", "without", "n't") and says
+ * something beyond that word. A coverage claim ("All screens", "Fully
+ * tested"), a placeholder ("N/A", "None at all", "Not applicable") and a
+ * denied limit ("No restrictions", "Nothing excluded") fail. "Desktop only",
+ * "Counted, not exercised" and "No queries ran as a signed-in user" pass.
+ *
+ * It reads English. It can't judge whether a limit is true or useful, only
+ * that one was written; a person still reads the scope.
+ */
+export declare function isVacuousScope(scope: string): boolean;
+/**
+ * What's wrong with a verification section's data, or an empty list. The
+ * section needs between one and {@link VERIFICATION_MAX_CHECKS} checks, and
+ * every field of every check is required, the scope most of all. Whatever
+ * stores a verification should run this first. The contract can't make it:
+ * until a write path calls it, stored data can hold anything, and
+ * {@link readVerificationChecks} is what keeps a bad check off the page.
+ */
+export declare function verificationProblems(data: unknown, options?: VerificationOptions): string[];
+/**
+ * The checks a renderer may show: the ones with every field present, within
+ * the limits, with a real day and a scope that states a limit, trimmed, in their
+ * stored order and no more than {@link VERIFICATION_MAX_CHECKS}. A check that
+ * fails is left out, so one with no scope line (or a placeholder for one) never
+ * prints. That's all it can promise: whether a scope is true is a person's call.
+ * Empty when the data is anything else. Single source of truth for what a case
+ * study prints from this section.
+ */
+export declare function readVerificationChecks(data: unknown, options?: VerificationOptions): VerificationCheck[];
+/**
+ * The link for a check's `where`: the address when it is exactly one http or
+ * https URL with no credentials in it and a public host, else null. A screen
+ * name or a file path is printed as text; nothing else is ever made into a link.
+ */
+export declare function verificationLink(where: string): string | null;
+/** Agent-native contract: JSON Schema for {@link PortfolioVerificationData}. What a scope or a where says, and whether a date is a real day in range, are checked by {@link verificationProblems}. */
+export declare const PORTFOLIO_VERIFICATION_JSON_SCHEMA: {
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+    readonly $id: 'https://sonor.io/schemas/portfolio-verification.v1.json';
+    readonly title: 'PortfolioVerificationData';
+    readonly description: 'A short list of checks on the finished build. Each says what was checked, where, how, when, what came out, and what it does not cover.';
+    readonly type: 'object';
+    readonly required: readonly ['checks'];
+    readonly properties: {
+        readonly checks: {
+            readonly type: 'array';
+            readonly minItems: 1;
+            readonly maxItems: 8;
+            readonly items: {
+                readonly type: 'object';
+                readonly required: readonly ["label", "result", "measured", "where", "method", "date", "scope"];
+                readonly properties: {
+                    readonly label: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 80;
+                    };
+                    readonly result: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 120;
+                    };
+                    readonly measured: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 200;
+                    };
+                    readonly where: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 200;
+                    };
+                    readonly method: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 240;
+                    };
+                    readonly date: {
+                        readonly type: 'string';
+                        readonly pattern: '^\\d{4}-\\d{2}-\\d{2}$';
+                    };
+                    readonly scope: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 240;
+                    };
+                };
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly additionalProperties: false;
+};
 /** Minimal KPI shape the policy reads — callers pass their own richer tiles. */
 export interface KpiLike {
     label: string;