@sonordev/contracts 1.0.0

package/dist/forms.mjs

@@ -0,0 +1,62 @@
+// src/contracts/forms.ts
+var FORMS_HONEYPOT_CONTRACT_VERSION = 1;
+var DEFAULT_HONEYPOT_FIELD = "_sk_hp_url";
+var GENERIC_HONEYPOT_FIELDS = Object.freeze([
+  DEFAULT_HONEYPOT_FIELD,
+  "website",
+  "_hp_field",
+  "bot-field",
+  "bot_field"
+]);
+function resolveHoneypotFieldNames(opts) {
+  const names = /* @__PURE__ */ new Set();
+  if (!opts.enabled) return names;
+  const real = new Set(opts.realFieldSlugs ?? []);
+  for (const generic of GENERIC_HONEYPOT_FIELDS) {
+    if (!real.has(generic)) names.add(generic);
+  }
+  if (opts.formHoneypotField) names.add(opts.formHoneypotField);
+  return names;
+}
+function isTrapFilled(value) {
+  if (value == null) return false;
+  if (typeof value === "string") return value.trim() !== "";
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) && value !== 0;
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+function findTrippedTrap(data, fieldNames) {
+  for (const field of fieldNames) {
+    const value = data?.[field];
+    if (!isTrapFilled(value)) continue;
+    if (Array.isArray(value)) return { field, valueType: "array", length: value.length };
+    const valueType = typeof value;
+    return {
+      field,
+      valueType: valueType === "string" ? "string" : valueType,
+      length: typeof value === "string" ? value.length : null
+    };
+  }
+  return null;
+}
+function isHoneypotTriggered(data, fieldNames) {
+  return findTrippedTrap(data, fieldNames) !== null;
+}
+var HONEYPOT_CONFIG_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/honeypot-config.v1.json",
+  title: "HoneypotConfig",
+  description: "The honeypot slice of a public managed-form config.",
+  type: "object",
+  properties: {
+    honeypot_enabled: { type: "boolean" },
+    honeypot_field: {
+      description: `Trap field name; defaults to "${DEFAULT_HONEYPOT_FIELD}" when unset.`,
+      type: "string"
+    }
+  },
+  additionalProperties: true
+};
+
+export { DEFAULT_HONEYPOT_FIELD, FORMS_HONEYPOT_CONTRACT_VERSION, GENERIC_HONEYPOT_FIELDS, HONEYPOT_CONFIG_JSON_SCHEMA, findTrippedTrap, isHoneypotTriggered, resolveHoneypotFieldNames };

package/dist/llms.d.ts

@@ -0,0 +1,54 @@
+/**
+ * GEO / AEO contract — shared shape for Sonor API, Signal API, and site-kit.
+ * Bump LLM_GEO_CONTRACT_VERSION when making breaking changes to public payloads.
+ *
+ * The APIs import it as `@sonordev/contracts/llms`; sites get the same code as
+ * `@sonordev/site-kit/seo/llms/contract`.
+ *
+ * @see LLM_GEO_CONTRACT.md in this folder
+ */
+/** Increment when public LLMs payload shape changes incompatibly. */
+export declare const LLM_GEO_CONTRACT_VERSION: 1;
+/** Max length for llms_public_summary (plain text, single line in llms.txt link notes). */
+export declare const LLMS_PUBLIC_SUMMARY_MAX_LENGTH = 400;
+/** Max length for optional llms.txt blockquote disclaimer line. */
+export declare const LLMS_DISCLAIMER_MAX_LENGTH = 280;
+/**
+ * Optional keys we allow inside managed_llm_schema JSON from Portal.
+ * Values outside this set should not be relied on by consumers; strip unknown keys when emitting JSON-LD.
+ */
+export declare const MANAGED_LLM_SCHEMA_KNOWN_KEYS: Set<string>;
+export interface LLMsPayloadMeta {
+    /** Contract version for this payload (matches LLM_GEO_CONTRACT_VERSION when current). */
+    contract_version: number;
+    /** ISO 8601 — best-effort freshness for the project’s SEO data. */
+    last_updated?: string | null;
+    /** BCP 47 tag for primary public content (e.g. from project settings). */
+    primary_language?: string | null;
+    /** Optional single-line, public-safe note in the llms.txt blockquote (e.g. scope / not legal advice). */
+    llms_disclaimer?: string | null;
+}
+/**
+ * Public-safe summary for llms.txt `[title](url): notes` — never CRM-only or internal copy.
+ */
+export declare function sanitizeLlmsPublicSummary(raw: unknown): string | null;
+/**
+ * Single line for llms.txt blockquote disclaimer — shorter min length than link notes.
+ */
+export declare function sanitizeLlmsDisclaimerLine(raw: unknown): string | null;
+/** Normalize BCP 47 tag for display (no quotes). */
+export declare function sanitizePrimaryLanguageTag(raw: unknown): string | null;
+/**
+ * Google requires `author` on every Review node and treats its absence as a
+ * CRITICAL error that suppresses review rich results for the whole page.
+ * Generated schema has shipped Review nodes carrying only `reviewBody` and
+ * `itemReviewed` — editorial prose about a client, not an attributed review —
+ * so they are invalid markup AND self-serving-review-policy risk.
+ *
+ * Single source of truth for "is this Review node safe to emit as JSON-LD".
+ * An author must resolve to a non-empty name; a bare `{"@type":"Review"}` and
+ * `author: {}` both fail.
+ */
+export declare function isEmittableReviewNode(node: Record<string, unknown>): boolean;
+/** Pick JSON-LD-safe subset of managed_llm_schema for script injection. */
+export declare function pickManagedLlmSchemaForJsonLd(schema: Record<string, unknown> | null | undefined): Record<string, unknown> | null;

package/dist/llms.js

@@ -0,0 +1,107 @@
+'use strict';
+
+// src/contracts/llms.ts
+var LLM_GEO_CONTRACT_VERSION = 1;
+var LLMS_PUBLIC_SUMMARY_MAX_LENGTH = 400;
+var LLMS_DISCLAIMER_MAX_LENGTH = 280;
+var MANAGED_LLM_SCHEMA_KNOWN_KEYS = /* @__PURE__ */ new Set([
+  "@context",
+  "@type",
+  "name",
+  "description",
+  "url",
+  "keywords",
+  "audience",
+  "about",
+  "mainEntity",
+  "isPartOf",
+  "speakable",
+  "additionalType"
+]);
+function sanitizeLlmsPublicSummary(raw) {
+  if (raw === null || raw === void 0) return null;
+  if (typeof raw !== "string") return null;
+  let s = raw.trim().replace(/\s+/g, " ");
+  s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
+  if (s.length > LLMS_PUBLIC_SUMMARY_MAX_LENGTH) {
+    s = `${s.slice(0, LLMS_PUBLIC_SUMMARY_MAX_LENGTH - 1).trimEnd()}\u2026`;
+  }
+  if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
+  if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
+  if (s.length < 8) return null;
+  return s;
+}
+function sanitizeLlmsDisclaimerLine(raw) {
+  if (raw === null || raw === void 0) return null;
+  if (typeof raw !== "string") return null;
+  let s = raw.trim().replace(/\s+/g, " ");
+  s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
+  if (s.length > LLMS_DISCLAIMER_MAX_LENGTH) {
+    s = `${s.slice(0, LLMS_DISCLAIMER_MAX_LENGTH - 1).trimEnd()}\u2026`;
+  }
+  if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
+  if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
+  if (s.length < 3) return null;
+  return s;
+}
+function sanitizePrimaryLanguageTag(raw) {
+  if (raw === null || raw === void 0) return null;
+  if (typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (!/^[\w-]{2,20}$/.test(s)) return null;
+  return s;
+}
+function isEmittableReviewNode(node) {
+  const author = node.author;
+  if (typeof author === "string") return author.trim().length > 0;
+  if (Array.isArray(author)) {
+    return author.some((a) => isEmittableReviewNode({ author: a }));
+  }
+  if (author && typeof author === "object") {
+    const name = author.name;
+    return typeof name === "string" && name.trim().length > 0;
+  }
+  return false;
+}
+var DROP = /* @__PURE__ */ Symbol("drop-invalid-review");
+function stripInvalidReviewNodes(value) {
+  if (Array.isArray(value)) {
+    return value.map((v) => stripInvalidReviewNodes(v)).filter((v) => v !== DROP);
+  }
+  if (value && typeof value === "object") {
+    const src = value;
+    if (src["@type"] === "Review" && !isEmittableReviewNode(src)) return DROP;
+    const out = {};
+    for (const key of Object.keys(src)) {
+      const child = stripInvalidReviewNodes(src[key]);
+      if (child === DROP) continue;
+      out[key] = child;
+    }
+    return out;
+  }
+  return value;
+}
+function pickManagedLlmSchemaForJsonLd(schema) {
+  if (!schema || typeof schema !== "object") return null;
+  const out = {};
+  const omitFromJsonLd = /* @__PURE__ */ new Set(["llms_public_summary"]);
+  for (const key of Object.keys(schema)) {
+    if (omitFromJsonLd.has(key)) continue;
+    if (MANAGED_LLM_SCHEMA_KNOWN_KEYS.has(key)) {
+      const value = stripInvalidReviewNodes(schema[key]);
+      if (value === DROP) continue;
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+exports.LLMS_DISCLAIMER_MAX_LENGTH = LLMS_DISCLAIMER_MAX_LENGTH;
+exports.LLMS_PUBLIC_SUMMARY_MAX_LENGTH = LLMS_PUBLIC_SUMMARY_MAX_LENGTH;
+exports.LLM_GEO_CONTRACT_VERSION = LLM_GEO_CONTRACT_VERSION;
+exports.MANAGED_LLM_SCHEMA_KNOWN_KEYS = MANAGED_LLM_SCHEMA_KNOWN_KEYS;
+exports.isEmittableReviewNode = isEmittableReviewNode;
+exports.pickManagedLlmSchemaForJsonLd = pickManagedLlmSchemaForJsonLd;
+exports.sanitizeLlmsDisclaimerLine = sanitizeLlmsDisclaimerLine;
+exports.sanitizeLlmsPublicSummary = sanitizeLlmsPublicSummary;
+exports.sanitizePrimaryLanguageTag = sanitizePrimaryLanguageTag;

package/dist/llms.mjs

@@ -0,0 +1,97 @@
+// src/contracts/llms.ts
+var LLM_GEO_CONTRACT_VERSION = 1;
+var LLMS_PUBLIC_SUMMARY_MAX_LENGTH = 400;
+var LLMS_DISCLAIMER_MAX_LENGTH = 280;
+var MANAGED_LLM_SCHEMA_KNOWN_KEYS = /* @__PURE__ */ new Set([
+  "@context",
+  "@type",
+  "name",
+  "description",
+  "url",
+  "keywords",
+  "audience",
+  "about",
+  "mainEntity",
+  "isPartOf",
+  "speakable",
+  "additionalType"
+]);
+function sanitizeLlmsPublicSummary(raw) {
+  if (raw === null || raw === void 0) return null;
+  if (typeof raw !== "string") return null;
+  let s = raw.trim().replace(/\s+/g, " ");
+  s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
+  if (s.length > LLMS_PUBLIC_SUMMARY_MAX_LENGTH) {
+    s = `${s.slice(0, LLMS_PUBLIC_SUMMARY_MAX_LENGTH - 1).trimEnd()}\u2026`;
+  }
+  if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
+  if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
+  if (s.length < 8) return null;
+  return s;
+}
+function sanitizeLlmsDisclaimerLine(raw) {
+  if (raw === null || raw === void 0) return null;
+  if (typeof raw !== "string") return null;
+  let s = raw.trim().replace(/\s+/g, " ");
+  s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
+  if (s.length > LLMS_DISCLAIMER_MAX_LENGTH) {
+    s = `${s.slice(0, LLMS_DISCLAIMER_MAX_LENGTH - 1).trimEnd()}\u2026`;
+  }
+  if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
+  if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
+  if (s.length < 3) return null;
+  return s;
+}
+function sanitizePrimaryLanguageTag(raw) {
+  if (raw === null || raw === void 0) return null;
+  if (typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (!/^[\w-]{2,20}$/.test(s)) return null;
+  return s;
+}
+function isEmittableReviewNode(node) {
+  const author = node.author;
+  if (typeof author === "string") return author.trim().length > 0;
+  if (Array.isArray(author)) {
+    return author.some((a) => isEmittableReviewNode({ author: a }));
+  }
+  if (author && typeof author === "object") {
+    const name = author.name;
+    return typeof name === "string" && name.trim().length > 0;
+  }
+  return false;
+}
+var DROP = /* @__PURE__ */ Symbol("drop-invalid-review");
+function stripInvalidReviewNodes(value) {
+  if (Array.isArray(value)) {
+    return value.map((v) => stripInvalidReviewNodes(v)).filter((v) => v !== DROP);
+  }
+  if (value && typeof value === "object") {
+    const src = value;
+    if (src["@type"] === "Review" && !isEmittableReviewNode(src)) return DROP;
+    const out = {};
+    for (const key of Object.keys(src)) {
+      const child = stripInvalidReviewNodes(src[key]);
+      if (child === DROP) continue;
+      out[key] = child;
+    }
+    return out;
+  }
+  return value;
+}
+function pickManagedLlmSchemaForJsonLd(schema) {
+  if (!schema || typeof schema !== "object") return null;
+  const out = {};
+  const omitFromJsonLd = /* @__PURE__ */ new Set(["llms_public_summary"]);
+  for (const key of Object.keys(schema)) {
+    if (omitFromJsonLd.has(key)) continue;
+    if (MANAGED_LLM_SCHEMA_KNOWN_KEYS.has(key)) {
+      const value = stripInvalidReviewNodes(schema[key]);
+      if (value === DROP) continue;
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+export { LLMS_DISCLAIMER_MAX_LENGTH, LLMS_PUBLIC_SUMMARY_MAX_LENGTH, LLM_GEO_CONTRACT_VERSION, MANAGED_LLM_SCHEMA_KNOWN_KEYS, isEmittableReviewNode, pickManagedLlmSchemaForJsonLd, sanitizeLlmsDisclaimerLine, sanitizeLlmsPublicSummary, sanitizePrimaryLanguageTag };

package/dist/portfolio.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @sonordev/contracts/portfolio — portfolio proof display policy (v1)
+ *
+ * Single source of truth for the Lighthouse-KPI collapse policy shared by the
+ * content side (signal-api generation) and the render side (agency-site-kit
+ * display):
+ *  - agency-site-kit imports it (`@sonordev/site-kit/portfolio/contract`)
+ *    from `src/portfolio/curate-proof.ts`, which keeps the render-only
+ *    primitives that bind to its section types.
+ *  - signal-api imports it through
+ *    `src/modules/skills/portfolio/portfolio-kpi-policy.util.ts`.
+ *
+ * Why it exists: generated case studies arrived with four "100/100 Lighthouse X"
+ * KPIs repeated across hero, results cards, and a Performance section. One
+ * differentiator repeated a dozen times stops differentiating — collapse the
+ * per-category Lighthouse tiles to at most one summary, business outcomes first.
+ *
+ * It is also the single source of truth for METRIC PROVENANCE (below): the
+ * three sources a portfolio number can have, what a client-reported number
+ * must carry, and which numbers may headline. sonor-api imports those
+ * through `src/modules/portfolio/portfolio-metric-source.util.ts`.
+ */
+/** 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;
+/** Bump on breaking changes to the collapse policy. */
+export declare const PORTFOLIO_CONTRACT_VERSION: 1;
+/** Minimal KPI shape the policy reads — callers pass their own richer tiles. */
+export interface KpiLike {
+    label: string;
+    value: number;
+    description?: string;
+}
+/** True when a KPI tile is a per-category Lighthouse score. */
+export declare function isLighthouseKpi(kpi: Pick<KpiLike, 'label'>): boolean;
+/**
+ * Collapse per-category Lighthouse KPIs to at most one summary tile, business
+ * outcomes first. When every category is present at 100 the summary says so;
+ * otherwise the Performance category (the one buyers know) represents the set.
+ * Fewer than two Lighthouse tiles → returned unchanged.
+ */
+export declare function curateHeroKpis<T extends KpiLike>(kpis: T[]): T[];
+/**
+ * Agent-native contract: JSON Schema for the minimal KPI shape, so services and
+ * agents can validate tiles before applying the collapse policy.
+ */
+export declare const PORTFOLIO_KPI_JSON_SCHEMA: {
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+    readonly $id: 'https://sonor.io/schemas/portfolio-kpi.v1.json';
+    readonly title: 'KpiLike';
+    readonly description: 'The subset of a portfolio KPI tile the Lighthouse-collapse policy reads.';
+    readonly type: 'object';
+    readonly required: readonly ['label', 'value'];
+    readonly properties: {
+        readonly label: {
+            readonly type: 'string';
+        };
+        readonly value: {
+            readonly type: 'number';
+        };
+        readonly description: {
+            readonly type: 'string';
+        };
+        readonly source: {
+            readonly enum: readonly ['measured', 'reported', 'estimated'];
+        };
+        readonly reportedBy: {
+            readonly type: 'object';
+            readonly required: readonly ['name', 'organization', 'date'];
+            readonly properties: {
+                readonly name: {
+                    readonly type: 'string';
+                    readonly minLength: 1;
+                };
+                readonly role: {
+                    readonly type: 'string';
+                };
+                readonly organization: {
+                    readonly type: 'string';
+                    readonly minLength: 1;
+                };
+                readonly date: {
+                    readonly type: 'string';
+                    readonly pattern: '^\\d{4}-\\d{2}-\\d{2}$';
+                };
+            };
+        };
+    };
+    readonly if: {
+        readonly properties: {
+            readonly source: {
+                readonly const: 'reported';
+            };
+        };
+        readonly required: readonly ['source'];
+    };
+    readonly then: {
+        readonly required: readonly ['reportedBy'];
+    };
+    readonly additionalProperties: true;
+};
+/** Every source a portfolio number can have. */
+export declare const METRIC_SOURCES: readonly ['measured', 'reported', 'estimated'];
+export type MetricSource = (typeof METRIC_SOURCES)[number];
+/** Who stands behind a client-reported number. */
+export interface MetricAttribution {
+    /** The person, e.g. "Scott Mann". */
+    name: string;
+    /** Their title, e.g. "Director of Business Development". */
+    role?: string;
+    /** Where they work: almost always the client, e.g. "True Power Systems". */
+    organization: string;
+    /** The day they reported it, YYYY-MM-DD. */
+    date: string;
+}
+/** The provenance fields a portfolio number (a KPI tile, a results card) carries. */
+export interface SourcedMetric {
+    source?: string | null;
+    reportedBy?: unknown;
+}
+export declare function isMetricSource(value: unknown): value is MetricSource;
+/**
+ * What's wrong with a number's provenance, or null when nothing is. A missing
+ * source is legacy data and passes (displays show it unlabelled, and it can't
+ * headline); an unknown source, or a reported number nobody is named behind,
+ * does not.
+ */
+export declare function metricSourceProblem(metric: SourcedMetric): string | null;
+/**
+ * May this number lead: a hero tile, a gallery card, a carousel, a social
+ * post? Measured, or reported with someone named behind it. Never an
+ * estimate, and never an unlabelled legacy number.
+ */
+export declare function isHeadlineMetric(metric: SourcedMetric): boolean;
+/** The badge a display shows, or null for a missing or unknown source (show nothing rather than guess). */
+export declare function metricSourceLabel(source: unknown): string | null;
+/**
+ * The full credit: "Reported by Scott Mann, Director of Business Development,
+ * True Power Systems, September 25, 2026". The date is read as a plain day,
+ * never through a time zone, so it can't slip to the day before.
+ */
+export declare function formatAttribution(by: MetricAttribution): string;
+/** The credit for a tight space (a card, a carousel tile): "per True Power Systems". */
+export declare function shortAttribution(by: Pick<MetricAttribution, 'organization'>): string;
+/**
+ * Carry a person's reported numbers through a regeneration. The generator can
+ * only write measured or estimated numbers (it can't see a client's books, and
+ * any 'reported' tag it writes is dropped here), so without this a rewrite of
+ * the hero or the results would silently erase what a client told us.
+ * Reported entries from `previous` lead, in their order; `next` fills in
+ * behind them, minus anything sharing a key with a reported entry.
+ */
+export declare function carryReportedMetrics<T extends SourcedMetric>(previous: readonly T[] | null | undefined, next: readonly T[] | null | undefined, keyOf: (metric: T) => string): T[];

package/dist/portfolio.js

@@ -0,0 +1,129 @@
+'use strict';
+
+// src/contracts/portfolio.ts
+var FRAME_READY_MESSAGE = "sonor:frame-ready";
+function isFrameReadyMessage(data) {
+  return !!data && typeof data === "object" && data.type === FRAME_READY_MESSAGE && data.v === 1;
+}
+var PORTFOLIO_CONTRACT_VERSION = 1;
+var LIGHTHOUSE_RE = /lighthouse/i;
+function isLighthouseKpi(kpi) {
+  return LIGHTHOUSE_RE.test(kpi.label || "");
+}
+function curateHeroKpis(kpis) {
+  const business = kpis.filter((k) => !isLighthouseKpi(k));
+  const lighthouse = kpis.filter(isLighthouseKpi);
+  if (lighthouse.length <= 1) return kpis;
+  const allPerfect = lighthouse.length >= 4 && lighthouse.every((k) => k.value === 100);
+  const summary = allPerfect ? {
+    ...lighthouse[0],
+    label: "Lighthouse, all 4 categories",
+    description: "Perfect scores across performance, SEO, accessibility, and best practices."
+  } : lighthouse.find((k) => /performance/i.test(k.label)) ?? lighthouse[0];
+  return [...business, summary];
+}
+var PORTFOLIO_KPI_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/portfolio-kpi.v1.json",
+  title: "KpiLike",
+  description: "The subset of a portfolio KPI tile the Lighthouse-collapse policy reads.",
+  type: "object",
+  required: ["label", "value"],
+  properties: {
+    label: { type: "string" },
+    value: { type: "number" },
+    description: { type: "string" },
+    source: { enum: ["measured", "reported", "estimated"] },
+    reportedBy: {
+      type: "object",
+      required: ["name", "organization", "date"],
+      properties: {
+        name: { type: "string", minLength: 1 },
+        role: { type: "string" },
+        organization: { type: "string", minLength: 1 },
+        date: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" }
+      }
+    }
+  },
+  // A reported number is only valid with someone named behind it.
+  if: { properties: { source: { const: "reported" } }, required: ["source"] },
+  then: { required: ["reportedBy"] },
+  additionalProperties: true
+};
+var METRIC_SOURCES = ["measured", "reported", "estimated"];
+var ISO_DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+var MONTHS = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December"
+];
+function isMetricSource(value) {
+  return typeof value === "string" && METRIC_SOURCES.includes(value);
+}
+function metricSourceProblem(metric) {
+  if (metric.source === void 0 || metric.source === null) return null;
+  if (!isMetricSource(metric.source)) return `source must be one of ${METRIC_SOURCES.join(", ")}`;
+  if (metric.source !== "reported") return null;
+  const by = metric.reportedBy;
+  if (!by || typeof by !== "object") {
+    return "a reported number needs reportedBy: who reported it, where they work, and when";
+  }
+  if (typeof by.name !== "string" || !by.name.trim()) return "reportedBy.name is required";
+  if (typeof by.organization !== "string" || !by.organization.trim()) {
+    return "reportedBy.organization is required";
+  }
+  if (typeof by.date !== "string" || !ISO_DAY_RE.test(by.date) || Number.isNaN(Date.parse(by.date))) {
+    return "reportedBy.date must be a real day, YYYY-MM-DD";
+  }
+  if (by.role !== void 0 && typeof by.role !== "string") return "reportedBy.role must be text";
+  return null;
+}
+function isHeadlineMetric(metric) {
+  if (metric.source === "measured") return true;
+  return metric.source === "reported" && metricSourceProblem(metric) === null;
+}
+function metricSourceLabel(source) {
+  if (source === "measured") return "Measured";
+  if (source === "reported") return "Client-reported";
+  if (source === "estimated") return "Estimated";
+  return null;
+}
+function formatAttribution(by) {
+  const [year, month, day] = by.date.split("-").map(Number);
+  const when = MONTHS[month - 1] ? `${MONTHS[month - 1]} ${day}, ${year}` : by.date;
+  return [`Reported by ${by.name.trim()}`, by.role?.trim(), by.organization.trim(), when].filter(Boolean).join(", ");
+}
+function shortAttribution(by) {
+  return `per ${by.organization.trim()}`;
+}
+function carryReportedMetrics(previous, next, keyOf) {
+  const norm = (metric) => String(keyOf(metric) ?? "").trim().toLowerCase();
+  const reported = (previous ?? []).filter((m) => m?.source === "reported");
+  const taken = new Set(reported.map(norm));
+  const generated = (next ?? []).filter((m) => m && m.source !== "reported" && !taken.has(norm(m)));
+  return [...reported, ...generated];
+}
+
+exports.FRAME_READY_MESSAGE = FRAME_READY_MESSAGE;
+exports.METRIC_SOURCES = METRIC_SOURCES;
+exports.PORTFOLIO_CONTRACT_VERSION = PORTFOLIO_CONTRACT_VERSION;
+exports.PORTFOLIO_KPI_JSON_SCHEMA = PORTFOLIO_KPI_JSON_SCHEMA;
+exports.carryReportedMetrics = carryReportedMetrics;
+exports.curateHeroKpis = curateHeroKpis;
+exports.formatAttribution = formatAttribution;
+exports.isFrameReadyMessage = isFrameReadyMessage;
+exports.isHeadlineMetric = isHeadlineMetric;
+exports.isLighthouseKpi = isLighthouseKpi;
+exports.isMetricSource = isMetricSource;
+exports.metricSourceLabel = metricSourceLabel;
+exports.metricSourceProblem = metricSourceProblem;
+exports.shortAttribution = shortAttribution;