geovouch 0.1.0 → 0.2.0

package/README.md

@@ -1,121 +1,54 @@
 # 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.
+Measure whether AI assistants name your brand when buyers ask them questions — know when that
+measurement can carry a decision, and prove whether what you shipped actually worked.
 
 ```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.*
+import { GeoVouch } from "geovouch";
+const gv = new GeoVouch({ apiKey: process.env.GEOVOUCH_API_KEY! });
 
----
+const { engines } = await gv.scoreboard();     // per engine, never averaged
+const { actionable } = await gv.gaps();        // only what the evidence can carry
+const brief = await gv.brief(actionable[0].question);
 
-## Knowing when you may act
+// …your agent writes and ships the page, in your stack …
 
-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";
+await gv.recordAction({ question: actionable[0].question, kind: "answer_page",
+                        url: "https://you.com/blog/x", publishedAt: new Date() });
 
-// 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
+const { assets } = await gv.lift();            // did it work?
 ```
 
-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.
+## What this package deliberately does not expose
 
----
-
-## The rest of the surface
-
-```ts
-import { buildBrandMatcher, buildCompetitorMatchers, namesIn } from "geovouch/matchers";
-import { groundedHosts, groundedQueryCount }                    from "geovouch/gemini";
-import { runGeoScan }                                           from "geovouch/runner";
-```
+No database, no migrations, no vendor token, no engine list to configure, no statistical parameter to
+tune. Those are ours — and keeping them ours is what lets the numbers get better without you
+redeploying.
 
-- **`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.
+## Three things the API refuses to blur
 
-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.
+**`unmeasured` is never `0`.** An engine that answered without retrieving has told you nothing about
+whether your pages were a source, so `sourcedRatePct` is `null` rather than zero. A lift verdict with
+no control is `unmeasured`, not "no effect".
 
----
+**Engines are never averaged.** They diverge by roughly 46×, so a single blended "AI visibility score"
+is the mean of four different instruments.
 
-## What this measures, and what it does not
+**A gap you may act on is not a gap you can see.** `gaps()` returns two lists. `actionable` cleared a
+precision floor, sat fully below the 50% win/loss line, and passed an anytime-valid familywise
+threshold — so you can check every morning without inflating your error rate. `researchOnly` did not,
+and spending on it is spending on a draw.
 
-`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.
+## The loop
 
-This library measures. It does not act, and it does not publish.
+`scoreboard` → `gaps` → `brief` → **you act, in your own stack** → `recordAction` → `lift`
 
----
+We never publish on your behalf: your agent already has the access, the conventions and the review
+rules, and any connector we built would be a worse version of what you already own. The receipt is the
+seam — it is what makes the last step possible for work we did not do.
 
 MIT © The Influence Company

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+export type GeoVouchOptions = {
+    apiKey: string;
+    /** Override for self-hosted or preview deployments. */
+    baseUrl?: string;
+    /** Required only when your key covers several projects. A project-scoped key ignores it. */
+    project?: string;
+    fetchImpl?: typeof fetch;
+};
+/** Every failure arrives as this, with the server's own sentence. A thrown string would make callers
+ *  parse prose to find out whether to retry. */
+export declare class GeoVouchError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+export declare class GeoVouch {
+    #private;
+    constructor(options: GeoVouchOptions);
+    /** Which projects this key can read. */
+    projects(): Promise<{
+        projects: {
+            id: string;
+            slug: string;
+            name: string;
+            scanEnabled: boolean;
+        }[];
+        keyScope: string;
+    }>;
+    /** Where you stand, per engine. Never averaged across engines — they diverge by ~46x, so one
+     *  blended score is the mean of four different instruments. */
+    scoreboard(): Promise<ScoreboardResponse>;
+    /** The buyer questions you are losing, split by whether the evidence can carry a decision.
+     *  `actionable` cleared precision, the 50% boundary and an anytime-valid familywise threshold;
+     *  `researchOnly` did not, and acting on it is acting on a draw. */
+    gaps(): Promise<GapsResponse>;
+    /** What to write for one actionable question. */
+    brief(question: string): Promise<Record<string, unknown>>;
+    /** Ranked next-best-actions. An EMPTY list means measured-and-nothing-to-do; it never means the
+     *  gate was shut — that arrives as a `collect_more_data` action naming the blocker. */
+    recommend(): Promise<{
+        actions: unknown[];
+    }>;
+    /** TELL US WHAT YOU DID. This is the verb that closes the loop: we never publish on your behalf, so
+     *  without a receipt your work is invisible to the step that measures whether it landed.
+     *
+     *  `publishedAt` is when the work went LIVE, not when you are reporting it — it is the before/after
+     *  pivot, and reporting Friday about a Tuesday page would count three days of "after" as before. */
+    recordAction(input: {
+        question: string;
+        kind: ActionKind;
+        url?: string;
+        publishedAt: Date | string;
+        note?: string;
+    }): Promise<{
+        action: unknown;
+        next: string;
+    }>;
+    /** Did it work? Control-adjusted, per engine, against a holdout arm nothing ever targets.
+     *  `unmeasured` means a window is missing or there is no control — it is not a zero. */
+    lift(): Promise<LiftResponse>;
+}
+export type ActionKind = "answer_page" | "page_strengthened" | "structured_data" | "docs_page" | "community_answer" | "third_party_listicle" | "backlink";
+export type EngineScore = {
+    engine: string;
+    status: "measured" | "unmeasured";
+    observations: number;
+    shareOfVoicePct?: number | null;
+    presenceRatePct?: number | null;
+    /** NULL, never 0, when nothing grounded: an engine that answered without retrieving has told you
+     *  nothing about whether your pages were a source. */
+    sourcedRatePct?: number | null;
+    confidence95?: {
+        shareOfVoicePct: {
+            low: number;
+            high: number;
+        } | null;
+        presenceRatePct: {
+            low: number;
+            high: number;
+        } | null;
+    };
+    lowConfidence?: boolean;
+    rivalsNamed?: number;
+    topRivals?: {
+        label: string;
+        count: number;
+    }[];
+};
+export type Readiness = {
+    actionable: boolean;
+    reasons: string[];
+};
+export type ProjectRef = {
+    id: string;
+    slug: string;
+    name: string;
+};
+export type ScoreboardResponse = {
+    project: ProjectRef;
+    readiness: Readiness;
+    engines: EngineScore[];
+};
+export type GapsResponse = {
+    project: ProjectRef;
+    readiness: Readiness;
+    actionable: Gap[];
+    researchOnly: Gap[];
+};
+export type Gap = {
+    question: string;
+    actionable: boolean;
+    citedRate?: number | null;
+    researchReasons?: string[];
+    competitors?: string[];
+};
+export type LiftResponse = {
+    project: ProjectRef;
+    holdoutArm: string[];
+    assets: {
+        slug: string;
+        question: string;
+        publishedAt: string;
+        /** Non-null means the after-window is not full yet. That resolves with TIME, not more content —
+         *  the distinction between "no effect" and "too early to say". */
+        daysUntilComparable: number | null;
+        engines: {
+            engine: string;
+            status: string;
+            proven: boolean;
+            netCiteLift: number | null;
+            verdict: string;
+        }[];
+    }[];
+    guidance: string;
+};

package/dist/index.js

@@ -0,0 +1,94 @@
+/** Every failure arrives as this, with the server's own sentence. A thrown string would make callers
+ *  parse prose to find out whether to retry. */
+export class GeoVouchError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "GeoVouchError";
+    }
+}
+const DEFAULT_BASE = "https://geovouch.zjudn2013.workers.dev";
+export class GeoVouch {
+    #key;
+    #base;
+    #project;
+    #fetch;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("geovouch: apiKey is required");
+        this.#key = options.apiKey;
+        this.#base = (options.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+        this.#project = options.project;
+        this.#fetch = options.fetchImpl ?? fetch;
+    }
+    async #call(path, init) {
+        const url = new URL(`${this.#base}/api/v1/${path}`);
+        if (this.#project)
+            url.searchParams.set("project", this.#project);
+        for (const [k, v] of Object.entries(init?.query ?? {}))
+            url.searchParams.set(k, v);
+        const res = await this.#fetch(url.toString(), {
+            method: init?.method ?? "GET",
+            // Bearer only. A key in a query string lands in access logs, proxy logs, browser history and
+            // Referer headers — none of which anyone thinks to rotate.
+            headers: { authorization: `Bearer ${this.#key}`, ...(init?.body ? { "content-type": "application/json" } : {}) },
+            body: init?.body ? JSON.stringify(init.body) : undefined,
+        });
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            throw new GeoVouchError(res.status, `geovouch: ${res.status} returned a non-JSON body`, text);
+        }
+        if (!res.ok) {
+            const message = parsed?.error;
+            throw new GeoVouchError(res.status, message || `geovouch: request failed (${res.status})`, parsed);
+        }
+        return parsed;
+    }
+    /** Which projects this key can read. */
+    projects() {
+        return this.#call("projects");
+    }
+    /** Where you stand, per engine. Never averaged across engines — they diverge by ~46x, so one
+     *  blended score is the mean of four different instruments. */
+    scoreboard() {
+        return this.#call("scoreboard");
+    }
+    /** The buyer questions you are losing, split by whether the evidence can carry a decision.
+     *  `actionable` cleared precision, the 50% boundary and an anytime-valid familywise threshold;
+     *  `researchOnly` did not, and acting on it is acting on a draw. */
+    gaps() {
+        return this.#call("gaps");
+    }
+    /** What to write for one actionable question. */
+    brief(question) {
+        return this.#call("brief", { query: { question } });
+    }
+    /** Ranked next-best-actions. An EMPTY list means measured-and-nothing-to-do; it never means the
+     *  gate was shut — that arrives as a `collect_more_data` action naming the blocker. */
+    recommend() {
+        return this.#call("recommend");
+    }
+    /** TELL US WHAT YOU DID. This is the verb that closes the loop: we never publish on your behalf, so
+     *  without a receipt your work is invisible to the step that measures whether it landed.
+     *
+     *  `publishedAt` is when the work went LIVE, not when you are reporting it — it is the before/after
+     *  pivot, and reporting Friday about a Tuesday page would count three days of "after" as before. */
+    recordAction(input) {
+        return this.#call("actions", {
+            method: "POST",
+            body: { ...input, publishedAt: input.publishedAt instanceof Date ? input.publishedAt.toISOString() : input.publishedAt },
+        });
+    }
+    /** Did it work? Control-adjusted, per engine, against a holdout arm nothing ever targets.
+     *  `unmeasured` means a window is missing or there is no control — it is not a zero. */
+    lift() {
+        return this.#call("lift");
+    }
+}

package/package.json

@@ -1,37 +1,28 @@
 {
   "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.",
+  "version": "0.2.0",
+  "description": "GeoVouch client — measure whether AI assistants name your brand, know when the evidence can carry a decision, and prove whether what you shipped worked. Bring an API key; the storage, the engines and the statistics are ours.",
   "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"
-  }
+  "node": ">=20"
+},
+"files": ["dist", "README.md", "LICENSE"],
+"repository": {
+"type": "git",
+"url": "git+https://github.com/theinfluencecompany/geovouch.git",
+"directory": "libs/client"
+},
+"keywords": ["geo", "aeo", "generative-engine-optimization", "ai-search", "share-of-voice", "llm", "brand-visibility"],
+"exports": {
+".": {
+"types": "./dist/index.d.ts",
+"default": "./dist/index.js"
+}
+},
+"scripts": {
+  "typecheck": "tsc -p tsconfig.json --noEmit",
+  "build": "tsc -p tsconfig.build.json",
+  "test": "node --test --experimental-transform-types test/*.test.ts"
+}
 }

package/dist/gemini.d.ts

@@ -1,28 +0,0 @@
-/** 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

@@ -1,62 +0,0 @@
-// 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

@@ -1,32 +0,0 @@
-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

@@ -1,46 +0,0 @@
-// 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

@@ -1,139 +0,0 @@
-/** 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

@@ -1,273 +0,0 @@
-// 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

@@ -1,58 +0,0 @@
-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

@@ -1,80 +0,0 @@
-// 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 };
-}