geovouch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Influence Company
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# geovouch
+
+Measure whether AI assistants name your brand when buyers ask them questions — and know when that
+measurement is strong enough to act on.
+
+Pure TypeScript. **Zero dependencies, zero IO.** Runs in a Cloudflare Worker, in Node, in a browser,
+in a test with no database.
+
+```bash
+npm i geovouch
+```
+
+---
+
+## The one idea
+
+**One row per (prompt × engine × repetition). Never a metric.**
+
+A grounded AI answer is non-deterministic. Two runs of the *same* prompt on the *same* engine within
+24 hours share only 0.32–0.43 of their source set (St. Gallen, arXiv:2604.07585). So a single reading
+per prompt is a coin flip, and a weekly dashboard number computed from one draw is noise with a
+decimal point.
+
+Everything here computes over a pooled window of atomic observations, and **never averages across
+engines** — they diverge by ~46×, so one blended "AI visibility score" is an average of four different
+instruments.
+
+```ts
+import { computeGeoWindow, type GeoObservation } from "geovouch/metrics";
+
+const observations: GeoObservation[] = [
+  { promptText: "best AI notetaker?", engine: "gemini", grounded: true,
+    brandMentioned: true, sourced: false, competitors: ["Otter"] },
+  // …one row per answer, pooled over your window
+];
+
+const w = computeGeoWindow(observations);
+w.sovPct;            // share of voice %, or null when nothing was named at all
+w.sovCi;             // { lo, hi } in pp — an observation-CLUSTER bootstrap, because one answer
+                     //   contributes several brand presences and they are not independent draws
+w.presenceRateCi;    // Wilson score interval — this one IS a Bernoulli rate
+w.sourcedRateCi;     // Wilson, over the GROUNDED observations only
+w.lowConfidence;     // true while any measured metric is wider than ±7pp
+w.denominatorWidth;  // distinct brands in the denominator — losing to 2 rivals ≠ losing to 20
+w.observations;      // the sample size. This IS the number that makes the rest readable.
+```
+
+`sovPct === null` means **nothing was named**, which is not a zero share. That distinction is load
+bearing throughout: *unmeasured is never a zero.*
+
+---
+
+## Knowing when you may act
+
+A dashboard number and a number you may spend money on are different things. The gate is explicit:
+
+```ts
+import { evaluatePromptGap, PROMPT_ACTION_FWER } from "geovouch/metrics";
+
+// 10 prompts × 4 engines = 40 hypotheses in the frozen family
+const decision = evaluatePromptGap(brandMentions, observations, 40);
+
+decision.status;  // "unmeasured" | "not_gap" | "research_only" | "proven_gap"
+decision.reasons; // why it is not proven yet, in sentences
+```
+
+Three independent conditions, and all of them must hold:
+
+| condition | what it rules out |
+|---|---|
+| Wilson 95% interval, half-width ≤ 7pp | a point estimate that a few more draws would move |
+| interval entirely below 50% | "we might be losing this question" |
+| anytime-valid e-value ≥ family size ÷ α | the 40-hypotheses-one-looks-significant problem |
+
+The third is the one most tools skip. It is a **one-sided finite-mixture Bernoulli e-process** against
+the composite null *p ≥ 0.5*, so **repeated daily looks cost no alpha** (Ville's inequality) — you can
+check every morning without inflating your error rate, which is exactly what a dashboard invites you
+to do. The threshold is e-Bonferroni: `familySize / α`, so 40 hypotheses at α=0.05 needs an e-value of
+**800**.
+
+At n≈216 per cell, roughly a third of genuinely-low prompts clear it. That is the honest yield, and a
+tool that reports more than that is reporting noise.
+
+> A bank change is a **ruler** change. Bump your prompt-bank version when the bank changes, or the
+> frozen hypothesis family silently grows past the denominator it is priced with.
+
+---
+
+## The rest of the surface
+
+```ts
+import { buildBrandMatcher, buildCompetitorMatchers, namesIn } from "geovouch/matchers";
+import { groundedHosts, groundedQueryCount }                    from "geovouch/gemini";
+import { runGeoScan }                                           from "geovouch/runner";
+```
+
+- **`geovouch/matchers`** — brand and competitor detection over answer prose. Handles the spaced form
+  of a CamelCase brand, which is how 93% of them actually appear.
+- **`geovouch/gemini`** — parse Gemini grounding metadata into retrieved hosts and billable query
+  counts. A host must be domain-shaped; a redirector is not a publisher.
+- **`geovouch/runner`** — the scan loop, with every engine and store injected as a **port**. No IO of
+  its own, so it is testable without a network.
+
+Storage, Cloudflare D1 wiring and the multi-engine Apify sweep live in sibling packages
+(`geovouch-store`, `geovouch-engines`). This package is the part with no opinions about where your
+data lives.
+
+---
+
+## What this measures, and what it does not
+
+`brandMentioned` is a regex over prose — a model can satisfy it from memory, or from a confabulation.
+`sourced` asks whether one of *your* domains was among the URLs the engine actually **retrieved**, and
+it is the only signal a model cannot produce from memory. It is `null`, never `false`, when an answer
+did not ground: an engine that answered without searching has told you nothing about your retrieval.
+
+This library measures. It does not act, and it does not publish.
+
+---
+
+MIT © The Influence Company

package/dist/gemini.d.ts

@@ -0,0 +1,28 @@
+/** Google's opaque grounding redirect. EVERY `web.uri` is one of these, so it is never a source — a
+ *  set containing only this host means "we read the wrong field", not "Google cited itself". */
+export declare const GROUNDING_REDIRECT_HOST = "vertexaisearch.cloud.google.com";
+/** Hostnames the engine retrieved, off Gemini's grounding metadata. Empty when the answer did not
+ *  ground.
+ *
+ *  READ `web.title`, NOT `web.uri`, AND NEVER `web.domain`. Measured: every chunk is
+ *  `{web:{uri,title}}`, `web.domain` is sent ZERO times — and @ai-sdk/google declares
+ *  `web: z.object({uri, title})`, so zod would strip a future `domain` before it reached us; a
+ *  fallback to it would read as a safety net while being unreachable code. Every `uri` is the opaque
+ *  redirect above. The publisher is in `title`, which on the Developer API is a bare domain — but not
+ *  contractually (Vertex puts page titles there), so a title is accepted only when it LOOKS like a
+ *  hostname; "Best AI apps | Some Site" is dropped rather than URL-parsed into garbage. */
+export declare function groundedHosts(providerMetadata: unknown): string[];
+/** Search queries the grounded answer actually executed — the unit Gemini 3.x BILLS on. The model
+ *  decides the fan-out per prompt (may be zero: a memory answer inside a grounded request), so a
+ *  prompt bank of a known size is NOT a bill of a known size; counting the answer is the only bound. */
+export declare function groundedQueryCount(providerMetadata: unknown): number;
+/** $14 per 1,000 search queries — ai.google.dev/gemini-api/docs/pricing, read 2026-09-01. The 2.5
+ *  line billed per grounded PROMPT; the 3.x line bills per SEARCH QUERY. The 5,000-free-per-month
+ *  allowance is deliberately NOT modelled: it is shared across every Gemini caller on an account, so
+ *  a second grounded call site would silently make the number wrong. Charging from the first query is
+ *  conservative and cannot drift. */
+export declare const GROUNDED_QUERY_CENTS = 1.4;
+/** What a run's grounded searches cost, in USD. The rate lives here and nowhere else — a console that
+ *  multiplied the query count by its own copy of the price would go quietly wrong the day Google
+ *  moves it. */
+export declare const groundedCostUsd: (searchQueries: number) => number;

package/dist/gemini.js

@@ -0,0 +1,62 @@
+// geovouch/gemini — grounding-metadata parsing for the Gemini Developer API. Product-agnostic: see
+// BOUNDARY.md. Every claim here was measured against the live API on 2026-09-04 (49 grounding chunks
+// across three calls through `ai` + `@ai-sdk/google`), because the first consumer shipped two months
+// of dead data by trusting a field the API never sends.
+/** Google's opaque grounding redirect. EVERY `web.uri` is one of these, so it is never a source — a
+ *  set containing only this host means "we read the wrong field", not "Google cited itself". */
+export const GROUNDING_REDIRECT_HOST = "vertexaisearch.cloud.google.com";
+/** Hostnames the engine retrieved, off Gemini's grounding metadata. Empty when the answer did not
+ *  ground.
+ *
+ *  READ `web.title`, NOT `web.uri`, AND NEVER `web.domain`. Measured: every chunk is
+ *  `{web:{uri,title}}`, `web.domain` is sent ZERO times — and @ai-sdk/google declares
+ *  `web: z.object({uri, title})`, so zod would strip a future `domain` before it reached us; a
+ *  fallback to it would read as a safety net while being unreachable code. Every `uri` is the opaque
+ *  redirect above. The publisher is in `title`, which on the Developer API is a bare domain — but not
+ *  contractually (Vertex puts page titles there), so a title is accepted only when it LOOKS like a
+ *  hostname; "Best AI apps | Some Site" is dropped rather than URL-parsed into garbage. */
+export function groundedHosts(providerMetadata) {
+    const meta = providerMetadata;
+    const chunks = meta?.google?.groundingMetadata?.groundingChunks ?? [];
+    const hosts = new Set();
+    for (const c of chunks) {
+        const host = hostFromTitle(c?.web?.title) ?? hostFromUri(c?.web?.uri);
+        if (host && host !== GROUNDING_REDIRECT_HOST)
+            hosts.add(host);
+    }
+    return [...hosts];
+}
+/** A bare hostname (`example.ai`, `www.reddit.com`) → normalized; anything else → null. */
+function hostFromTitle(title) {
+    const t = title?.trim().toLowerCase();
+    if (!t || !/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(t))
+        return null;
+    return t.replace(/^www\./, "");
+}
+function hostFromUri(uri) {
+    if (!uri)
+        return null;
+    try {
+        return new URL(uri.startsWith("http") ? uri : `https://${uri}`).hostname.replace(/^www\./, "");
+    }
+    catch {
+        return null;
+    }
+}
+/** Search queries the grounded answer actually executed — the unit Gemini 3.x BILLS on. The model
+ *  decides the fan-out per prompt (may be zero: a memory answer inside a grounded request), so a
+ *  prompt bank of a known size is NOT a bill of a known size; counting the answer is the only bound. */
+export function groundedQueryCount(providerMetadata) {
+    const meta = providerMetadata;
+    return meta?.google?.groundingMetadata?.webSearchQueries?.length ?? 0;
+}
+/** $14 per 1,000 search queries — ai.google.dev/gemini-api/docs/pricing, read 2026-09-01. The 2.5
+ *  line billed per grounded PROMPT; the 3.x line bills per SEARCH QUERY. The 5,000-free-per-month
+ *  allowance is deliberately NOT modelled: it is shared across every Gemini caller on an account, so
+ *  a second grounded call site would silently make the number wrong. Charging from the first query is
+ *  conservative and cannot drift. */
+export const GROUNDED_QUERY_CENTS = 1.4;
+/** What a run's grounded searches cost, in USD. The rate lives here and nowhere else — a console that
+ *  multiplied the query count by its own copy of the price would go quietly wrong the day Google
+ *  moves it. */
+export const groundedCostUsd = (searchQueries) => Math.round(searchQueries * GROUNDED_QUERY_CENTS) / 100;

package/dist/matchers.d.ts

@@ -0,0 +1,32 @@
+export type BrandConfig = {
+    /** The brand word as engines write it, e.g. "Acme". Matched word-bounded, case-insensitive. */
+    name: string;
+    /** Registrable domains that count as the brand's own pages among retrieved sources ("acme.ai"
+     *  matches itself and any subdomain). */
+    domains: readonly string[];
+    /** Extra spellings that also count as a mention (a common misspelling, a former name). */
+    aliases?: readonly string[];
+};
+export type BrandMatcher = {
+    /** Was the brand NAMED in the prose? A model can satisfy this from memory or confabulation — pair
+     *  it with `sourcedHost` on retrieved sources, which it cannot fake. */
+    mentioned(answer: string): boolean;
+    /** Is this retrieved host one of ours? */
+    sourcedHost(host: string): boolean;
+};
+export declare function buildBrandMatcher(config: BrandConfig): BrandMatcher;
+export type CompetitorMatcher = {
+    label: string;
+    re: RegExp;
+};
+/** Build presence matchers for a competitor set. Tokenizes labels at BOTH kinds of boundary — the
+ *  separators an engine may drop, and the CamelCase seam an all-together label hides — then rejoins
+ *  with an optional separator: "AcmeAI" → /\bAcme[.\s-]?AI\b/i, matching "Acme AI", "AcmeAI" and
+ *  "Acme.AI" alike. The FULL domain is the second alternative, never its root. */
+export declare function buildCompetitorMatchers(competitors: readonly {
+    domain: string;
+    label: string;
+}[]): CompetitorMatcher[];
+/** Competitor labels named in one answer — the atoms of share-of-voice's denominator. A false
+ *  positive here is indistinguishable from the measured brand losing ground. */
+export declare function namesIn(answer: string, matchers: readonly CompetitorMatcher[]): string[];

package/dist/matchers.js

@@ -0,0 +1,46 @@
+// geovouch/matchers — brand + competitor presence detection over engine answer text. Product-agnostic:
+// see BOUNDARY.md. Every rule here was paid for by a measured incident on the first consumer, so the
+// rules travel with the code:
+//   * A competitor is matched by LABEL (separator- AND CamelCase-flexible) or FULL DOMAIN — never a
+//     bare domain root. A rival on a `<noun>.ai` domain whose root is an everyday word the measured
+//     product's own copy uses constantly once matched as `\b<noun>\b` and scored a presence on 8/10
+//     answers against a true 5/10 — and every false positive is a point in share-of-voice's
+//     DENOMINATOR, i.e. it pushes the measured brand DOWN.
+//   * CamelCase must tokenize, because engines write the spaced form: a stored one-token label
+//     ("AcmeAI") against the written spaced form ("Acme AI") missed ~93% of real namings
+//     (1 of 15 measured).
+//   * "AI" never splits internally — the seam is lower/digit → UPPER, so consecutive capitals stay
+//     whole and a label like "PopUp" does not become a match for the ordinary phrase "pop up".
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+export function buildBrandMatcher(config) {
+    const spellings = [config.name, ...(config.aliases ?? [])].filter(Boolean).map(escapeRe);
+    const re = new RegExp(`\\b(?:${spellings.join("|")})\\b`, "i");
+    const domains = config.domains.map((d) => d.toLowerCase());
+    return {
+        mentioned: (answer) => re.test(answer),
+        sourcedHost: (host) => {
+            const h = host.toLowerCase();
+            return domains.some((d) => h === d || h.endsWith(`.${d}`));
+        },
+    };
+}
+/** Build presence matchers for a competitor set. Tokenizes labels at BOTH kinds of boundary — the
+ *  separators an engine may drop, and the CamelCase seam an all-together label hides — then rejoins
+ *  with an optional separator: "AcmeAI" → /\bAcme[.\s-]?AI\b/i, matching "Acme AI", "AcmeAI" and
+ *  "Acme.AI" alike. The FULL domain is the second alternative, never its root. */
+export function buildCompetitorMatchers(competitors) {
+    return competitors.map((c) => {
+        const tokens = c.label
+            .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+            .split(/[.\s-]+/)
+            .filter(Boolean)
+            .map(escapeRe);
+        const label = tokens.join("[.\\s-]?");
+        return { label: c.label, re: new RegExp(`\\b${label}\\b|\\b${escapeRe(c.domain)}\\b`, "i") };
+    });
+}
+/** Competitor labels named in one answer — the atoms of share-of-voice's denominator. A false
+ *  positive here is indistinguishable from the measured brand losing ground. */
+export function namesIn(answer, matchers) {
+    return matchers.filter((c) => c.re.test(answer)).map((c) => c.label);
+}

package/dist/metrics.d.ts

@@ -0,0 +1,139 @@
+/** One atomic observation: a single answer to one prompt on one engine. */
+export type GeoObservation = {
+    promptText: string;
+    engine: string;
+    /** Did this answer actually retrieve? The denominator for `sourced`. */
+    grounded: boolean;
+    /** Was the measured brand NAMED in the prose? */
+    brandMentioned: boolean;
+    /** Was one of the brand's own domains among the retrieved sources? null when the answer did not
+     *  ground. */
+    sourced: boolean | null;
+    /** Competitor labels named in this one answer. */
+    competitors: string[];
+};
+export type GeoWindowSummary = {
+    /** Share of voice %: brand presences / (brand + competitor presences), 0-100. NULL when the
+     *  denominator is empty — nothing was named at all, which is not a zero share. Rounded to 0.1 for
+     *  storage AFTER the internal share is computed at full precision (Elmo's rule — an intermediate
+     *  integer percentage rounds small shares away). */
+    sovPct: number | null;
+    /** Presence rate %: observations naming the brand / total observations, 0-100. NULL when empty. */
+    presenceRatePct: number | null;
+    /** Sourced rate %: GROUNDED observations where a brand domain was a source / grounded observations.
+     *  The metric a model cannot fake. NULL when nothing grounded — you cannot be a source of nothing. */
+    sourcedRatePct: number | null;
+    /** DISTINCT brands named at least once (the measured brand counts only if it appeared). The
+     *  denominator's WIDTH — a low SoV against 2 rivals and against 20 are different facts. */
+    denominatorWidth: number;
+    /** Atomic observations pooled = sample size. 0 ⇒ measured nothing. */
+    observations: number;
+    /** Observations that actually grounded — the honest sourced denominator. */
+    groundedObservations: number;
+    /** Competitor labels by presence share, most-present first. Counts, not rates, so a reader can see
+     *  the raw tally. */
+    competitors: {
+        label: string;
+        count: number;
+    }[];
+    /** 95% confidence intervals (in %) for the three metrics: observation-cluster bootstrap for SoV,
+     *  Wilson score intervals for the two Bernoulli rates. A number without its interval is a claim
+     *  without its uncertainty; a thin sample shows a WIDE interval, which is the honest signal. NULL
+     *  when the metric's denominator is empty. */
+    sovCi: Interval | null;
+    presenceRateCi: Interval | null;
+    sourcedRateCi: Interval | null;
+    /** True when ANY measured headline metric is too imprecise: its farthest 95% bound lies more than
+     *  `MAX_CI_HALF_WIDTH_PP` from the point estimate. A low-confidence number must be shown as a RANGE,
+     *  never as a headline figure, and a lift claim inside it is unprovable. */
+    lowConfidence: boolean;
+};
+/** A confidence interval in percent (0-100), low/high bounds. */
+export type Interval = {
+    lo: number;
+    hi: number;
+};
+/** The field's replicated noise floor is roughly ±5–7pp. A point estimate is too imprecise to
+ *  headline when its 95% CI has a half-width above 7pp (14pp full width). */
+export declare const MAX_CI_HALF_WIDTH_PP = 7;
+export declare const MAX_CI_WIDTH_PP: number;
+/** An intervention smaller than 7pp is not practically distinguishable from ordinary run-to-run
+ *  movement even if a very large sample eventually makes it statistically significant. */
+export declare const MIN_LIFT_PP = 7;
+/** Familywise false-action budget for a frozen prompt-bank version. Repeated looks are handled by the
+ *  e-process itself; this alpha is divided only across the fixed prompt × engine hypothesis family. */
+export declare const PROMPT_ACTION_FWER = 0.05;
+export type PromptGapEvidence = {
+    /** Current mixture e-value. It may fall after a previous crossing; acting on the first crossing is
+     *  still protected by Ville's inequality. */
+    eValue: number;
+    /** e-Bonferroni threshold = fixed hypothesis-family size / familywise alpha. */
+    threshold: number;
+    hypothesisCount: number;
+    familywiseAlpha: number;
+    proven: boolean;
+};
+/** Anytime-valid evidence that one prompt-engine mention rate is below 50%. The observation stream must
+ *  be scoped to ONE frozen prompt-bank version and must include only complete scans. Repeated dashboard,
+ *  MCP and cron looks spend no extra alpha; e-Bonferroni controls the fixed prompt × engine family under
+ *  arbitrary dependence. Wilson intervals remain a separate display/precision rule. */
+export declare function promptGapEvidence(brandMentions: number, observations: number, hypothesisCount: number, familywiseAlpha?: number): PromptGapEvidence;
+/** Unrounded Wilson bounds in percentage points. Contrast estimators consume these directly so
+ *  intermediate rounding cannot move a final lift interval across zero. */
+export declare function wilsonCiBounds(successes: number, total: number, z?: number): Interval | null;
+/** 95% Wilson score interval for a binomial proportion `successes/total`, returned in PERCENT and
+ *  rounded for display/storage. NULL when total=0. Wilson behaves correctly at small n and 0%/100%. */
+export declare function wilsonCi(successes: number, total: number, z?: number): Interval | null;
+/** Full width of an interval in pp; Infinity for a null (unmeasured) interval. */
+export declare const ciWidth: (ci: Interval | null) => number;
+/** The field threshold is about uncertainty around THE estimate, not half of an asymmetric interval's
+ * full width. Wilson intervals near 0%/100% are one-sided, so use the farther endpoint. */
+export declare const ciMargin: (estimate: number | null, ci: Interval | null) => number;
+export type PromptGapDecision = {
+    status: "unmeasured" | "not_gap" | "research_only" | "proven_gap";
+    citedRate: number | null;
+    citedRateCi: Interval | null;
+    confidenceReady: boolean;
+    evidence: PromptGapEvidence;
+    reasons: string[];
+};
+/** The one action gate for a prompt on one engine. The Wilson interval answers whether the estimate is
+ *  precise enough to explain; the e-process answers whether repeated looks plus the fixed family still
+ *  permit action. Callers must supply the FULL frozen prompt × engine family size, not the number of
+ *  rows that happened to answer. */
+export declare function evaluatePromptGap(brandMentions: number, observations: number, hypothesisCount: number, familywiseAlpha?: number): PromptGapDecision;
+/** Deterministic cluster bootstrap for share of voice. One answer can name several rivals, so its SoV
+ *  contributions are not Bernoulli trials and a Wilson interval over raw brand+rival mentions would
+ *  be falsely narrow. Resampling whole observations preserves that within-answer clustering. A
+ *  cluster-effective Wilson floor prevents the percentile bootstrap's known zero-width failure when
+ *  a small sample lands entirely at 0% or 100%. */
+export declare function bootstrapSovCi(observations: readonly GeoObservation[], samples?: number): Interval | null;
+/** Aggregate a window of observations into one summary. Pure. Elmo's `computeReportMetrics` shape:
+ *  share = brand / (brand + competitors), presence = brand / total, sourced = sourced / grounded, each
+ *  with an explicit empty-denominator → null (never a divide, never a misleading 0). */
+export declare function computeGeoWindow(observations: readonly GeoObservation[]): GeoWindowSummary;
+/** Per-prompt aggregation for the ACTIVE LOOP: which buyer questions the brand is losing, and to whom,
+ *  over the window. A prompt is a "gap" when the brand is named in a MINORITY of its observations —
+ *  pooled, not a single draw. Ranked worst-first: most-uncited, then most-competitors-present. */
+export type GeoPromptWindow = {
+    promptText: string;
+    observations: number;
+    brandMentions: number;
+    /** 0-1: brandMentions / observations. Below 0.5 ⇒ we lose this question more often than we win it. */
+    citedRate: number;
+    /** 95% Wilson interval in 0-1 units for agent-facing ranking and confidence gating. */
+    citedRateCi: {
+        lo: number;
+        hi: number;
+    };
+    /** True when the rate is wider than the headline precision floor OR its interval crosses the 50%
+     *  win/loss boundary. A point estimate below 50% is not an actionable loss until its upper bound is
+     *  also below 50%. */
+    lowConfidence: boolean;
+    /** Competitor labels named across this prompt's window, by frequency. */
+    competitors: {
+        label: string;
+        count: number;
+    }[];
+};
+export declare function computeGeoPromptWindows(observations: readonly GeoObservation[]): GeoPromptWindow[];

package/dist/metrics.js

@@ -0,0 +1,273 @@
+// geovouch/metrics — the pure math over atomic prompt-run observations. Product-agnostic: see BOUNDARY.md.
+//
+// PORTED FROM Elmo (elmohq/elmo, MIT — packages/lib/src/report-metrics.ts + apps/web/src/lib/
+// visibility-stats.ts), whose design centre is exactly ours: keep the formulas framework-free and
+// DB-free so they run anywhere (a Worker over D1 rows here, a page over Postgres rows there) and are
+// unit-testable without a database. This module is client-safe and imports nothing from lib/server.
+//
+// The reading is a WINDOW aggregate, never a single scan. A grounded answer is non-deterministic
+// (measured: 0.32-0.43 source-set overlap between two runs of one prompt on one engine within 24h), so
+// a single draw per prompt is noise; the field pools repetition over a rolling window. That is the
+// whole reason the storage is one-row-per-observation — see schema/geo.ts.
+/** The field's replicated noise floor is roughly ±5–7pp. A point estimate is too imprecise to
+ *  headline when its 95% CI has a half-width above 7pp (14pp full width). */
+export const MAX_CI_HALF_WIDTH_PP = 7;
+export const MAX_CI_WIDTH_PP = MAX_CI_HALF_WIDTH_PP * 2;
+/** An intervention smaller than 7pp is not practically distinguishable from ordinary run-to-run
+ *  movement even if a very large sample eventually makes it statistically significant. */
+export const MIN_LIFT_PP = 7;
+/** Familywise false-action budget for a frozen prompt-bank version. Repeated looks are handled by the
+ *  e-process itself; this alpha is divided only across the fixed prompt × engine hypothesis family. */
+export const PROMPT_ACTION_FWER = 0.05;
+/** A fixed mixture of plausible loss rates. Each likelihood ratio is a test supermartingale for the
+ *  composite null p>=50%; averaging them remains anytime-valid without choosing an effect after seeing
+ *  the answers. This list is policy, so a change requires a prompt-bank-version reset. */
+const PROMPT_GAP_ALTERNATIVES = [0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45];
+/** Anytime-valid evidence that one prompt-engine mention rate is below 50%. The observation stream must
+ *  be scoped to ONE frozen prompt-bank version and must include only complete scans. Repeated dashboard,
+ *  MCP and cron looks spend no extra alpha; e-Bonferroni controls the fixed prompt × engine family under
+ *  arbitrary dependence. Wilson intervals remain a separate display/precision rule. */
+export function promptGapEvidence(brandMentions, observations, hypothesisCount, familywiseAlpha = PROMPT_ACTION_FWER) {
+    if (!Number.isSafeInteger(brandMentions) ||
+        !Number.isSafeInteger(observations) ||
+        brandMentions < 0 ||
+        observations < 0 ||
+        brandMentions > observations)
+        throw new RangeError("brandMentions and observations must be valid integer counts");
+    if (!Number.isSafeInteger(hypothesisCount) || hypothesisCount <= 0) {
+        throw new RangeError("hypothesisCount must be a positive safe integer");
+    }
+    if (!Number.isFinite(familywiseAlpha) || familywiseAlpha <= 0 || familywiseAlpha >= 1) {
+        throw new RangeError("familywiseAlpha must be between 0 and 1");
+    }
+    const failures = observations - brandMentions;
+    const logTerms = PROMPT_GAP_ALTERNATIVES.map((alternative) => brandMentions * Math.log(alternative / 0.5) +
+        failures * Math.log((1 - alternative) / 0.5));
+    const maxLog = Math.max(...logTerms);
+    const logEValue = maxLog +
+        Math.log(logTerms.reduce((total, value) => total + Math.exp(value - maxLog), 0) / PROMPT_GAP_ALTERNATIVES.length);
+    const threshold = hypothesisCount / familywiseAlpha;
+    return {
+        eValue: Math.exp(Math.min(logEValue, Math.log(Number.MAX_VALUE))),
+        threshold,
+        hypothesisCount,
+        familywiseAlpha,
+        proven: logEValue >= Math.log(threshold),
+    };
+}
+const pct = (num, den) => (den <= 0 ? null : Math.round((num / den) * 1000) / 10);
+/** Unrounded Wilson bounds in percentage points. Contrast estimators consume these directly so
+ *  intermediate rounding cannot move a final lift interval across zero. */
+export function wilsonCiBounds(successes, total, z = 1.96) {
+    if (!Number.isFinite(successes) || !Number.isFinite(total) || !Number.isFinite(z) || total <= 0 || successes < 0 || successes > total || z <= 0)
+        return null;
+    const p = successes / total;
+    const z2 = z * z;
+    const denom = 1 + z2 / total;
+    const center = (p + z2 / (2 * total)) / denom;
+    const half = (z / denom) * Math.sqrt((p * (1 - p)) / total + z2 / (4 * total * total));
+    const clamp = (x) => Math.max(0, Math.min(1, x)) * 100;
+    return { lo: clamp(center - half), hi: clamp(center + half) };
+}
+/** 95% Wilson score interval for a binomial proportion `successes/total`, returned in PERCENT and
+ *  rounded for display/storage. NULL when total=0. Wilson behaves correctly at small n and 0%/100%. */
+export function wilsonCi(successes, total, z = 1.96) {
+    const ci = wilsonCiBounds(successes, total, z);
+    return ci ? { lo: Math.round(ci.lo * 10) / 10, hi: Math.round(ci.hi * 10) / 10 } : null;
+}
+/** Full width of an interval in pp; Infinity for a null (unmeasured) interval. */
+export const ciWidth = (ci) => (ci ? ci.hi - ci.lo : Infinity);
+/** The field threshold is about uncertainty around THE estimate, not half of an asymmetric interval's
+ * full width. Wilson intervals near 0%/100% are one-sided, so use the farther endpoint. */
+export const ciMargin = (estimate, ci) => estimate === null || !ci ? Infinity : Math.max(estimate - ci.lo, ci.hi - estimate);
+/** The one action gate for a prompt on one engine. The Wilson interval answers whether the estimate is
+ *  precise enough to explain; the e-process answers whether repeated looks plus the fixed family still
+ *  permit action. Callers must supply the FULL frozen prompt × engine family size, not the number of
+ *  rows that happened to answer. */
+export function evaluatePromptGap(brandMentions, observations, hypothesisCount, familywiseAlpha = PROMPT_ACTION_FWER) {
+    const evidence = promptGapEvidence(brandMentions, observations, hypothesisCount, familywiseAlpha);
+    const estimatePct = observations > 0 ? (brandMentions / observations) * 100 : null;
+    const bounds = wilsonCiBounds(brandMentions, observations);
+    const citedRateCi = bounds
+        ? {
+            lo: Math.round(bounds.lo * 10) / 10,
+            hi: Math.round(bounds.hi * 10) / 10,
+        }
+        : null;
+    const citedRate = estimatePct === null ? null : estimatePct / 100;
+    const confidenceReady = estimatePct !== null &&
+        bounds !== null &&
+        bounds.hi < 50 &&
+        ciMargin(estimatePct, bounds) <= MAX_CI_HALF_WIDTH_PP;
+    if (estimatePct === null) {
+        return {
+            status: "unmeasured",
+            citedRate,
+            citedRateCi,
+            confidenceReady,
+            evidence,
+            reasons: ["no observations in the current prompt-bank version"],
+        };
+    }
+    if (estimatePct >= 50) {
+        return {
+            status: "not_gap",
+            citedRate,
+            citedRateCi,
+            confidenceReady: false,
+            evidence,
+            reasons: ["the brand is named in at least half of observations"],
+        };
+    }
+    const reasons = [];
+    if (!bounds || bounds.hi >= 50) {
+        reasons.push("the 95% Wilson interval does not lie wholly below 50%");
+    }
+    if (!bounds || ciMargin(estimatePct, bounds) > MAX_CI_HALF_WIDTH_PP) {
+        reasons.push(`the 95% interval extends more than ±${MAX_CI_HALF_WIDTH_PP}pp from the estimate`);
+    }
+    if (!evidence.proven) {
+        reasons.push(`the anytime-valid familywise e-value ${evidence.eValue.toPrecision(3)} is below ${evidence.threshold.toFixed(0)}`);
+    }
+    return {
+        status: confidenceReady && evidence.proven ? "proven_gap" : "research_only",
+        citedRate,
+        citedRateCi,
+        confidenceReady,
+        evidence,
+        reasons,
+    };
+}
+/** Deterministic cluster bootstrap for share of voice. One answer can name several rivals, so its SoV
+ *  contributions are not Bernoulli trials and a Wilson interval over raw brand+rival mentions would
+ *  be falsely narrow. Resampling whole observations preserves that within-answer clustering. A
+ *  cluster-effective Wilson floor prevents the percentile bootstrap's known zero-width failure when
+ *  a small sample lands entirely at 0% or 100%. */
+export function bootstrapSovCi(observations, samples = 10_000) {
+    const contributions = observations
+        .map((o) => ({ brand: o.brandMentioned ? 1 : 0, rivals: o.competitors.length }))
+        .sort((a, b) => a.brand - b.brand || a.rivals - b.rivals);
+    const brand = contributions.reduce((total, x) => total + x.brand, 0);
+    const mentionWeights = contributions.map((x) => x.brand + x.rivals);
+    const mentions = mentionWeights.reduce((total, weight) => total + weight, 0);
+    if (mentions === 0 || samples <= 0)
+        return null;
+    let state = 0x9e3779b9;
+    const shares = [];
+    for (let sample = 0; sample < samples; sample++) {
+        let sampleBrand = 0;
+        let sampleRivals = 0;
+        for (let draw = 0; draw < contributions.length; draw++) {
+            state ^= state << 13;
+            state ^= state >>> 17;
+            state ^= state << 5;
+            const picked = contributions[(state >>> 0) % contributions.length];
+            sampleBrand += picked.brand;
+            sampleRivals += picked.rivals;
+        }
+        if (sampleBrand + sampleRivals > 0)
+            shares.push((sampleBrand / (sampleBrand + sampleRivals)) * 100);
+    }
+    if (!shares.length)
+        return null;
+    shares.sort((a, b) => a - b);
+    const quantile = (q) => shares[Math.min(shares.length - 1, Math.max(0, Math.floor(q * shares.length)))];
+    const bootstrap = { lo: quantile(0.025), hi: quantile(0.975) };
+    // Kish effective sample size treats each answer as one cluster and discounts answers that contribute
+    // many rival mentions. Fractional Wilson successes are the SoV estimate at that effective n.
+    const squaredWeights = mentionWeights.reduce((total, weight) => total + weight * weight, 0);
+    const effectiveN = (mentions * mentions) / squaredWeights;
+    const floor = wilsonCi((brand / mentions) * effectiveN, effectiveN);
+    return {
+        lo: Math.round(Math.min(bootstrap.lo, floor.lo) * 10) / 10,
+        hi: Math.round(Math.max(bootstrap.hi, floor.hi) * 10) / 10,
+    };
+}
+/** Aggregate a window of observations into one summary. Pure. Elmo's `computeReportMetrics` shape:
+ *  share = brand / (brand + competitors), presence = brand / total, sourced = sourced / grounded, each
+ *  with an explicit empty-denominator → null (never a divide, never a misleading 0). */
+export function computeGeoWindow(observations) {
+    let brandPresences = 0;
+    let competitorPresences = 0;
+    let groundedObservations = 0;
+    let sourcedObservations = 0;
+    const competitorsSeen = new Set();
+    const competitorCounts = new Map();
+    for (const o of observations) {
+        if (o.brandMentioned)
+            brandPresences += 1;
+        for (const label of o.competitors) {
+            competitorPresences += 1;
+            competitorsSeen.add(label.toLowerCase());
+            competitorCounts.set(label, (competitorCounts.get(label) ?? 0) + 1);
+        }
+        if (o.grounded) {
+            groundedObservations += 1;
+            if (o.sourced === true)
+                sourcedObservations += 1;
+        }
+    }
+    const total = observations.length;
+    const sovPct = pct(brandPresences, brandPresences + competitorPresences);
+    const presenceRatePct = pct(brandPresences, total);
+    const sourcedRatePct = pct(sourcedObservations, groundedObservations);
+    const sovCi = bootstrapSovCi(observations);
+    const presenceRateCi = wilsonCi(brandPresences, total);
+    const sourcedRateCi = wilsonCi(sourcedObservations, groundedObservations);
+    return {
+        sovPct,
+        presenceRatePct,
+        sourcedRatePct,
+        denominatorWidth: competitorsSeen.size + (brandPresences > 0 ? 1 : 0),
+        observations: total,
+        groundedObservations,
+        competitors: [...competitorCounts.entries()]
+            .map(([label, count]) => ({ label, count }))
+            .sort((a, b) => b.count - a.count || a.label.localeCompare(b.label)),
+        sovCi,
+        presenceRateCi,
+        sourcedRateCi,
+        // A window with NO observations makes every metric null, so every `x !== null` test is false and
+        // the OR was FALSE — an engine that measured nothing reported as high-confidence, which the header
+        // then persisted and the MCP scoreboard rendered as "every metric is within ±7pp". Nothing measured
+        // is the least confident state there is.
+        lowConfidence: total === 0 ||
+            (sovPct !== null && ciMargin(sovPct, sovCi) > MAX_CI_HALF_WIDTH_PP) ||
+            (presenceRatePct !== null && ciMargin(presenceRatePct, presenceRateCi) > MAX_CI_HALF_WIDTH_PP) ||
+            (sourcedRatePct !== null && ciMargin(sourcedRatePct, sourcedRateCi) > MAX_CI_HALF_WIDTH_PP),
+    };
+}
+export function computeGeoPromptWindows(observations) {
+    const byPrompt = new Map();
+    for (const o of observations) {
+        const arr = byPrompt.get(o.promptText);
+        if (arr)
+            arr.push(o);
+        else
+            byPrompt.set(o.promptText, [o]);
+    }
+    const out = [];
+    for (const [promptText, obs] of byPrompt) {
+        const brandMentions = obs.filter((o) => o.brandMentioned).length;
+        const counts = new Map();
+        for (const o of obs)
+            for (const c of o.competitors)
+                counts.set(c, (counts.get(c) ?? 0) + 1);
+        const citedRateCiPct = wilsonCi(brandMentions, obs.length) ?? { lo: 0, hi: 100 };
+        const citedRate = obs.length > 0 ? brandMentions / obs.length : 0;
+        const crossesDecisionBoundary = citedRate < 0.5 ? citedRateCiPct.hi >= 50 : citedRateCiPct.lo < 50;
+        out.push({
+            promptText,
+            observations: obs.length,
+            brandMentions,
+            citedRate,
+            citedRateCi: {
+                lo: Math.round(citedRateCiPct.lo * 10) / 1000,
+                hi: Math.round(citedRateCiPct.hi * 10) / 1000,
+            },
+            lowConfidence: ciMargin(citedRate * 100, citedRateCiPct) > MAX_CI_HALF_WIDTH_PP || crossesDecisionBoundary,
+            competitors: [...counts.entries()].map(([label, count]) => ({ label, count })).sort((a, b) => b.count - a.count),
+        });
+    }
+    return out.sort((a, b) => a.citedRate - b.citedRate || b.competitors.length - a.competitors.length);
+}

package/dist/runner.d.ts

@@ -0,0 +1,58 @@
+import { type BrandConfig } from "./matchers.ts";
+import type { GeoObservation } from "./metrics.ts";
+/** One measured row plus the non-metric facts a consumer usually stores beside it. */
+export type GeoScanRow = GeoObservation & {
+    citedHosts: string[];
+    searchQueries: number;
+};
+export type GeoScanConfig = {
+    brand: BrandConfig;
+    competitors: readonly {
+        domain: string;
+        label: string;
+    }[];
+    prompts: readonly string[];
+    /** The row's engine label, e.g. "gemini-grounded". The aggregator groups by it and never averages
+     *  across engines — they diverge wildly. */
+    engine: string;
+    /** Whether `ask` runs with retrieval. Controls both the system nudge and whether grounding metadata
+     *  is read. An ungrounded scan's `sourced` is always null (unmeasured, never false). */
+    grounded: boolean;
+    /** Answers per prompt per scan. Default 1 — a rolling window across scans pools better than a burst
+     *  on one day (portfolio-level, measured by the field); raise only alongside a cadence change. */
+    repetitions?: number;
+    /** Override the system prompt. The default asks for concrete app/product recommendations and, when
+     *  grounded, to search first. */
+    system?: {
+        grounded?: string;
+        ungrounded?: string;
+    };
+};
+export type GeoScanPorts = {
+    /** One LLM call. Throwing loses this observation only. */
+    ask(prompt: string, system: string): Promise<{
+        text?: string | null;
+        providerMetadata?: unknown;
+    }>;
+    /** Persist one row as it is measured. Catch your own storage errors — a throw here also costs only
+     *  this observation. */
+    onObservation?(row: GeoScanRow): void | Promise<void>;
+    /** Polled before every call; true stops the scan with a stoppedReason. */
+    budget?: {
+        overBudget(): boolean;
+    };
+};
+export type GeoScanResult = {
+    observations: GeoScanRow[];
+    /** Raw answer texts, for a consumer's own mining pass. Never persisted by the kit. */
+    answers: {
+        prompt: string;
+        answer: string;
+    }[];
+    /** Retrieved hosts per prompt (accumulated across repetitions) — venue analysis reads this. */
+    hostsByPrompt: Map<string, string[]>;
+    /** Billable search queries across the scan — the only honest bound on a grounded bill. */
+    searchQueries: number;
+    stoppedReason: string | null;
+};
+export declare function runGeoScan(config: GeoScanConfig, ports: GeoScanPorts): Promise<GeoScanResult>;

package/dist/runner.js

@@ -0,0 +1,80 @@
+// geovouch/runner — the generic scan loop, with every side effect injected as a port. The kit stays
+// IO-free by construction: it never imports an LLM client, a database or a clock — the consumer hands
+// in `ask` (one LLM call) and optionally `onObservation` (persist one row) and `budget` (spend guard),
+// and the runner owns only the loop's SHAPE: repetition, fail-soft per observation, grounded-answer
+// parsing, brand/competitor detection.
+//
+// This shape is lifted from the first consumer's production loop, where it ran daily against grounded
+// Gemini. What each port is for, learned there:
+//   * `ask` returns the raw text + providerMetadata; a throw inside it loses ONE observation, never
+//     the scan (no fake data is ever recorded for a failed call).
+//   * `budget.overBudget()` is polled before every call, because a grounded prompt's search fan-out is
+//     the model's choice, not the caller's — the bank size does not bound the bill; only counting the
+//     answers does (see gemini.ts).
+//   * `onObservation` receives each row as it is measured, so storage is append-per-row and a failed
+//     insert (the port's own catch) costs one row, never the scan.
+import { buildBrandMatcher, buildCompetitorMatchers, namesIn } from "./matchers.js";
+import { groundedHosts, groundedQueryCount } from "./gemini.js";
+const DEFAULT_GROUNDED_SYSTEM = "You are a helpful assistant recommending apps. SEARCH THE WEB FIRST, then answer naturally and concretely, naming specific apps you'd recommend based on what you found.";
+const DEFAULT_UNGROUNDED_SYSTEM = "You are a helpful assistant recommending apps. Answer naturally and concretely, naming specific apps you'd recommend.";
+export async function runGeoScan(config, ports) {
+    const brand = buildBrandMatcher(config.brand);
+    const matchers = buildCompetitorMatchers(config.competitors);
+    const repetitions = config.repetitions ?? 1;
+    const system = config.grounded
+        ? (config.system?.grounded ?? DEFAULT_GROUNDED_SYSTEM)
+        : (config.system?.ungrounded ?? DEFAULT_UNGROUNDED_SYSTEM);
+    const observations = [];
+    const answers = [];
+    const hostsByPrompt = new Map();
+    let searchQueries = 0;
+    let stoppedReason = null;
+    for (const prompt of config.prompts) {
+        for (let rep = 0; rep < repetitions; rep++) {
+            if (ports.budget?.overBudget()) {
+                stoppedReason = `budget reached after ${searchQueries} search queries`;
+                break;
+            }
+            let answer = "";
+            let hosts = [];
+            let queries = 0;
+            try {
+                const { text, providerMetadata } = await ports.ask(prompt, system);
+                answer = text ?? "";
+                hosts = config.grounded ? groundedHosts(providerMetadata) : [];
+                queries = config.grounded ? groundedQueryCount(providerMetadata) : 0;
+                searchQueries += queries;
+            }
+            catch {
+                continue; // this observation just doesn't contribute (no fake data)
+            }
+            // Grounding is per-ANSWER: a memory answer inside a grounded scan retrieved nothing, so its
+            // sourced is null (unmeasured), never false.
+            const grounded = queries > 0 || hosts.length > 0;
+            const row = {
+                promptText: prompt,
+                engine: config.engine,
+                grounded,
+                brandMentioned: brand.mentioned(answer),
+                sourced: grounded ? hosts.some((h) => brand.sourcedHost(h)) : null,
+                competitors: namesIn(answer, matchers),
+                citedHosts: hosts,
+                searchQueries: queries,
+            };
+            observations.push(row);
+            if (answer)
+                answers.push({ prompt, answer });
+            if (hosts.length)
+                hostsByPrompt.set(prompt, [...(hostsByPrompt.get(prompt) ?? []), ...hosts]);
+            try {
+                await ports.onObservation?.(row);
+            }
+            catch {
+                /* a failed persist costs one row, never the scan */
+            }
+        }
+        if (stoppedReason)
+            break;
+    }
+    return { observations, answers, hostsByPrompt, searchQueries, stoppedReason };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "geovouch",
+  "version": "0.1.0",
+  "description": "GeoVouch measurement core — GEO (Generative Engine Optimization) share-of-voice over atomic prompt observations: window metrics, brand/competitor matchers, grounding-metadata parsing, and a port-injected scan runner. Pure TypeScript, zero dependencies, zero IO.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./metrics": {
+      "types": "./dist/metrics.d.ts",
+      "default": "./dist/metrics.js"
+    },
+    "./matchers": {
+      "types": "./dist/matchers.d.ts",
+      "default": "./dist/matchers.js"
+    },
+    "./gemini": {
+      "types": "./dist/gemini.d.ts",
+      "default": "./dist/gemini.js"
+    },
+    "./runner": {
+      "types": "./dist/runner.d.ts",
+      "default": "./dist/runner.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test --experimental-transform-types test/*.test.ts",
+    "boundary": "node ../../scripts/check-boundary.mjs"
+  }
+}