fullstackgtm 0.15.0 → 0.16.0

package/src/cli.ts

@@ -39,6 +39,17 @@ import { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./
 import { builtinAuditRules } from "./rules.ts";
 import { sampleSnapshot } from "./sampleData.ts";
 import { normalizeTranscript, parseCall, suggestCallDeal, type ExtractedCallInsight, type ParsedCall } from "./calls.ts";
+import {
+  captureMarket,
+  computeFrontStates,
+  createFileObservationStore,
+  diffFrontStates,
+  loadMarketConfig,
+  starterMarketConfig,
+  validateObservationSet,
+  type ObservationSet,
+} from "./market.ts";
+import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 import {
   DEFAULT_RUBRIC,
   detectProviderFromKey,
@@ -94,6 +105,15 @@ Usage:
   fullstackgtm resolve <account|contact|deal> [--name N] [--domain D] [--email E] [--account-id A] [source options] [--json]
                                                the create gate: exit 0 = safe to create, exit 2 = match
                                                found (exists/ambiguous) — call before ANY record creation
+  fullstackgtm market init --category <name>   start a market map: vendors + claim taxonomy as reviewable config
+  fullstackgtm market capture [--config <path>] [--run <label>]
+  fullstackgtm market observe --from <observations.json>
+  fullstackgtm market fronts [--run <label>] [--diff <prior-run>] [--json]
+  fullstackgtm market report [--run <label>] [--format md|html] [--out <path>]
+                                               the live competitive map: capture vendor pages (content-addressed),
+                                               ingest intensity readings with verbatim-quote evidence, compute
+                                               deterministic front states (open/contested/owned/saturated) and
+                                               drift between runs, render the client-ready field report
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -801,6 +821,126 @@ function buildCallPlan(
   };
 }
 
+/**
+ * The market map: claim taxonomy in a reviewable config file, page captures
+ * and append-only observations under the profile home, deterministic front
+ * states and reports computed from the store. Classification (LLM intensity
+ * readings) lands in a later change; until then `market observe --from`
+ * ingests proposal files produced by an agent or a human.
+ */
+async function marketCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+  const configPath = () => resolve(process.cwd(), option(rest, "--config") ?? "market.config.json");
+
+  if (!subcommand || subcommand === "--help") {
+    console.log(`Usage:
+market init --category <name> [--out <path>]   write a starter market.config.json
+market capture [--config <path>] [--run <label>]
+market observe --from <observations.json> [--config <path>]
+market fronts [--config <path>] [--run <label>] [--diff <prior-run>] [--json]
+market report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
+
+The taxonomy (vendors + claims) is config you review and version; captures
+and observations live under ~/.fullstackgtm/market/<category> (profile-scoped,
+one client's category intel never bleeds into another's). Front states are
+recomputed deterministically on every invocation — never stored.`);
+    return;
+  }
+
+  if (subcommand === "init") {
+    const category = option(rest, "--category");
+    if (!category) throw new Error("market init requires --category <name>");
+    const outPath = resolve(process.cwd(), option(rest, "--out") ?? "market.config.json");
+    if (existsSync(outPath)) throw new Error(`${outPath} already exists — refusing to overwrite`);
+    writeFileSync(outPath, `${JSON.stringify(starterMarketConfig(category), null, 2)}\n`);
+    console.log(`Wrote ${outPath}. Fill in vendors and claims, then: fullstackgtm market capture`);
+    return;
+  }
+
+  const config = loadMarketConfig(configPath());
+  const store = createFileObservationStore(config.category);
+
+  if (subcommand === "capture") {
+    const result = await captureMarket(config, { runLabel: option(rest, "--run") ?? "run-1" });
+    for (const entry of result.entries) {
+      const flag = entry.captureHash && entry.textChars > 500 ? "" : "  <-- thin/empty";
+      console.log(
+        `${entry.vendorId.padEnd(16)} ${entry.kind.padEnd(8)} ${String(entry.httpStatus ?? "ERR").padEnd(4)} ${String(entry.textChars).padStart(7)} chars  ${entry.url}${flag}`,
+      );
+    }
+    console.log(`\nmanifest: ${result.manifestPath}`);
+    return;
+  }
+
+  if (subcommand === "observe") {
+    const fromPath = option(rest, "--from");
+    if (!fromPath) throw new Error("market observe requires --from <observations.json>");
+    const set = JSON.parse(readFileSync(resolve(process.cwd(), fromPath), "utf8")) as ObservationSet;
+    const problems = validateObservationSet(config, set);
+    if (problems.length > 0) {
+      console.error(`Rejected: ${problems.length} problem(s)`);
+      for (const problem of problems.slice(0, 20)) console.error(`  - ${problem}`);
+      process.exitCode = 1;
+      return;
+    }
+    await store.append(set);
+    console.log(`Appended ${set.runLabel}: ${set.observations.length} observations (${set.extractor})`);
+    return;
+  }
+
+  const loadSet = async (): Promise<ObservationSet> => {
+    const runLabel = option(rest, "--run");
+    const set = runLabel ? await store.get(runLabel) : await store.latest();
+    if (!set) {
+      throw new Error(
+        runLabel
+          ? `No observation run "${runLabel}" for ${config.category}`
+          : `No observations stored for ${config.category} — run market observe --from <file> first`,
+      );
+    }
+    return set;
+  };
+
+  if (subcommand === "fronts") {
+    const set = await loadSet();
+    const fronts = computeFrontStates(config, set);
+    const priorLabel = option(rest, "--diff");
+    const prior = priorLabel ? await store.get(priorLabel) : null;
+    if (priorLabel && !prior) throw new Error(`No observation run "${priorLabel}" to diff against`);
+    const drift = prior ? diffFrontStates(computeFrontStates(config, prior), fronts) : null;
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify({ runLabel: set.runLabel, fronts, drift }, null, 2));
+      return;
+    }
+    for (const front of fronts) {
+      const owner = front.state === "owned" ? ` → ${front.loudVendorIds[0]}` : "";
+      console.log(`${front.state.toUpperCase().padEnd(10)} ${front.claimId}${owner}`);
+    }
+    if (drift) {
+      console.log("");
+      if (drift.length === 0) console.log(`No front changes since ${priorLabel}.`);
+      for (const change of drift) console.log(`CHANGED   ${change.claimId}: ${change.before} → ${change.after}`);
+    }
+    return;
+  }
+
+  if (subcommand === "report") {
+    const set = await loadSet();
+    const format = option(rest, "--format") ?? "md";
+    const output = format === "html" ? marketMapToHtml(config, set) : marketMapToMarkdown(config, set);
+    const outPath = option(rest, "--out");
+    if (outPath) {
+      writeFileSync(resolve(process.cwd(), outPath), output);
+      console.log(`Wrote ${outPath}`);
+    } else {
+      console.log(output);
+    }
+    return;
+  }
+
+  throw new Error(`Unknown market subcommand: ${subcommand} (try: init, capture, observe, fronts, report)`);
+}
+
 /**
  * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
  * ambiguous — do NOT blind-create), exit 1 = error. Built for sync jobs and
@@ -1665,6 +1805,10 @@ export async function runCli(argv: string[]) {
     await resolveCommand(args);
     return;
   }
+  if (command === "market") {
+    await marketCommand(args);
+    return;
+  }
   if (command === "profiles") {
     profilesCommand(args);
     return;

package/src/connectors/hubspot.ts

@@ -431,7 +431,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
             created = await request(`/crm/v3/objects/companies`, {
               method: "POST",
               body: JSON.stringify({
-                properties: { name, hs_object_source_detail_2: "fullstackgtm create: operation" },
+                properties: { name, hs_object_source_detail_2: `fullstackgtm create: (${operation.id})` },
               }),
             });
           } catch {

package/src/index.ts

@@ -130,6 +130,33 @@ export {
   type ScoredDimension,
 } from "./llm.ts";
 export { resolveRecord, type ResolveCandidate, type ResolveMatch, type ResolveResult } from "./resolve.ts";
+export {
+  captureMarket,
+  computeFrontStates,
+  createFileObservationStore,
+  diffFrontStates,
+  extractReadableText,
+  loadMarketConfig,
+  marketHome,
+  observationId,
+  parseMarketConfig,
+  starterMarketConfig,
+  validateObservationSet,
+  type CaptureEntry,
+  type CaptureOptions,
+  type ClaimFront,
+  type ClaimIntensity,
+  type FrontDrift,
+  type FrontState,
+  type MarketClaim,
+  type MarketConfig,
+  type MarketObservation,
+  type MarketVendor,
+  type ObservationConfidence,
+  type ObservationSet,
+  type ObservationStore,
+} from "./market.ts";
+export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type {
   ApprovalStatus,

package/src/market.ts

@@ -0,0 +1,467 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { credentialsDir } from "./credentials.ts";
+import type { GtmEvidence } from "./types.ts";
+
+/**
+ * The Market Map: a live model of the competitive category a company sells
+ * into. Vendors publish claims constantly (pricing pages, feature pages,
+ * hero copy); each (vendor × claim) cell gets a messaging-intensity reading,
+ * and each claim row gets a derived front state. Observations are
+ * append-only — history is the product; "what changed since last run" is a
+ * first-class question.
+ *
+ * Division of labor mirrors call intelligence: intensity readings are
+ * *proposals* (LLM or human, always with verbatim quoted evidence), while
+ * everything downstream — front states, drift, the report — is deterministic
+ * over the stored observations. Same stored observations, same map.
+ *
+ * The claim taxonomy and vendor registry live in a reviewable config file
+ * (git-friendly, analyst-edited); captures and observations live under the
+ * profile home so one client's category intel never bleeds into another's.
+ */
+
+export type ClaimIntensity = "loud" | "quiet" | "absent" | "unobservable";
+
+export type ObservationConfidence = "high" | "medium" | "low";
+
+export type FrontState = "open" | "contested" | "owned" | "saturated" | "vacant";
+
+export type MarketClaim = {
+  id: string;
+  /** The capability being claimed, precise enough to judge loud/quiet/absent. */
+  capability: string;
+  /** Which ICP the claim cell addresses (category-specific vocabulary). */
+  icp: string;
+  /** Which pricing structure the claim cell implies (category-specific). */
+  pricingStructure: string;
+  /** Operational definition: how a reader judges LOUD vs QUIET vs ABSENT. */
+  definition: string;
+};
+
+export type MarketVendor = {
+  id: string;
+  name: string;
+  urls: {
+    home: string;
+    /** null is itself an observation: no public pricing surface. */
+    pricing: string | null;
+    product: string[];
+  };
+  notes?: string;
+};
+
+export type MarketConfig = {
+  category: string;
+  anchorVendor?: string;
+  vendors: MarketVendor[];
+  claims: MarketClaim[];
+  /** The LOUD/QUIET/ABSENT/UNOBSERVABLE judging rule, stated for reviewers. */
+  surfaceRule?: string;
+};
+
+export type MarketObservation = {
+  /** stableHash(category, runLabel, vendorId, claimId) — deterministic. */
+  id: string;
+  vendorId: string;
+  claimId: string;
+  observedAt: string;
+  intensity: ClaimIntensity;
+  confidence: ObservationConfidence;
+  /** Reviewer-facing: why the reading is what it is. */
+  reason: string;
+  /**
+   * Verbatim quoted spans grounding any non-absent reading
+   * (sourceSystem "web", metadata.url + metadata.captureHash).
+   */
+  evidence: GtmEvidence[];
+};
+
+export type ObservationSet = {
+  id: string;
+  category: string;
+  runLabel: string;
+  runAt: string;
+  /** What produced the readings: "manual" or "llm:<provider>:<model>". */
+  extractor: string;
+  observations: MarketObservation[];
+};
+
+export type CaptureEntry = {
+  runLabel: string;
+  vendorId: string;
+  kind: "home" | "pricing" | "product";
+  url: string;
+  fetchedAt: string;
+  httpStatus: number | null;
+  /** sha256 of the extracted text; null when the fetch failed or was empty. */
+  captureHash: string | null;
+  textChars: number;
+};
+
+const INTENSITY_RANK: Record<ClaimIntensity, number> = {
+  loud: 3,
+  quiet: 2,
+  absent: 1,
+  unobservable: 0,
+};
+
+// Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep market.ts
+// importable without pulling the audit engine.
+function fnv1a(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export function observationId(category: string, runLabel: string, vendorId: string, claimId: string): string {
+  return `obs_${fnv1a(`${category}|${runLabel}|${vendorId}|${claimId}`)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Config
+
+export function parseMarketConfig(raw: string): MarketConfig {
+  const config = JSON.parse(raw) as MarketConfig;
+  if (!config.category) throw new Error("market config: missing category");
+  if (!Array.isArray(config.vendors) || config.vendors.length === 0) {
+    throw new Error("market config: at least one vendor is required");
+  }
+  if (!Array.isArray(config.claims) || config.claims.length === 0) {
+    throw new Error("market config: at least one claim is required");
+  }
+  for (const [label, items] of [
+    ["vendor", config.vendors],
+    ["claim", config.claims],
+  ] as const) {
+    const seen = new Set<string>();
+    for (const item of items) {
+      if (!item.id) throw new Error(`market config: ${label} missing id`);
+      if (seen.has(item.id)) throw new Error(`market config: duplicate ${label} id "${item.id}"`);
+      seen.add(item.id);
+    }
+  }
+  if (config.anchorVendor && !config.vendors.some((v) => v.id === config.anchorVendor)) {
+    throw new Error(`market config: anchorVendor "${config.anchorVendor}" is not in vendors`);
+  }
+  return config;
+}
+
+export function loadMarketConfig(path: string): MarketConfig {
+  return parseMarketConfig(readFileSync(path, "utf8"));
+}
+
+export function starterMarketConfig(category: string): MarketConfig {
+  return {
+    category,
+    anchorVendor: "your-company",
+    vendors: [
+      {
+        id: "your-company",
+        name: "Your Company",
+        urls: { home: "https://example.com/", pricing: null, product: [] },
+        notes: "Replace with the real vendor set (≤10 works well). pricing: null records 'no public pricing page'.",
+      },
+    ],
+    claims: [
+      {
+        id: "example-claim",
+        capability: "Example capability: what is being claimed, stated precisely",
+        icp: "who-buys-it",
+        pricingStructure: "how-it-is-priced",
+        definition:
+          "LOUD if the claim is hero copy or a top-nav named product with a dedicated page; QUIET if it appears only on pages below that; ABSENT if nowhere. Write the definition so a human could judge any vendor's page against it.",
+      },
+    ],
+    surfaceRule:
+      "LOUD = hero copy OR top-level-nav named product with dedicated page; QUIET = present on any indexed page below that; ABSENT = nowhere observed (explicit disavowals score ABSENT with the disavowal quoted in reason); UNOBSERVABLE = capture empty/failed — never score ABSENT from a failed capture.",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Profile-scoped market home: captures and observations live with credentials
+// so --profile isolation covers category intel too.
+
+export function marketHome(category: string, baseDir?: string): string {
+  return join(baseDir ?? credentialsDir(), "market", category);
+}
+
+// ---------------------------------------------------------------------------
+// Capture: fetch vendor pages, strip to readable text, store content-addressed.
+// The hash cache is the change detector (unchanged page = same hash = no new
+// classification needed), the replay buffer (re-judge a revised taxonomy
+// without re-scraping), and the evidence chain (quoted spans stay resolvable).
+
+const STRIP_BLOCKS = /<(script|style|noscript|svg|head)\b[\s\S]*?<\/\1\s*>/gi;
+const ENTITIES: Record<string, string> = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#39;": "'",
+  "&apos;": "'",
+  "&nbsp;": " ",
+  "&mdash;": "—",
+  "&ndash;": "–",
+};
+
+export function extractReadableText(html: string): string {
+  const withoutBlocks = html.replace(STRIP_BLOCKS, " ");
+  const withBreaks = withoutBlocks.replace(/<(\/p|\/div|\/li|\/h[1-6]|br\s*\/?)>/gi, "\n");
+  const withoutTags = withBreaks.replace(/<[^>]+>/g, " ");
+  const decoded = withoutTags
+    .replace(/&[a-z#0-9]+;/gi, (entity) => ENTITIES[entity.toLowerCase()] ?? " ")
+    .replace(/[ \t]+/g, " ");
+  return decoded
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join("\n");
+}
+
+export type FetchPage = (url: string) => Promise<{ status: number; body: string }>;
+
+const defaultFetchPage: FetchPage = async (url) => {
+  const response = await fetch(url, {
+    headers: {
+      "User-Agent": "fullstackgtm-market/0 (+https://github.com/fullstackgtm/core)",
+      "Accept-Language": "en-US",
+    },
+    redirect: "follow",
+  });
+  return { status: response.status, body: await response.text() };
+};
+
+export type CaptureOptions = {
+  /** Directory for captures; defaults to <marketHome>/captures. */
+  dir?: string;
+  runLabel?: string;
+  /** Injectable for tests; defaults to global fetch. */
+  fetchPage?: FetchPage;
+  now?: () => Date;
+};
+
+export type CaptureResult = {
+  entries: CaptureEntry[];
+  manifestPath: string;
+};
+
+export async function captureMarket(config: MarketConfig, options: CaptureOptions = {}): Promise<CaptureResult> {
+  const dir = options.dir ?? join(marketHome(config.category), "captures");
+  const runLabel = options.runLabel ?? "run-1";
+  const fetchPage = options.fetchPage ?? defaultFetchPage;
+  const fetchedAt = (options.now ?? (() => new Date()))().toISOString();
+  mkdirSync(dir, { recursive: true });
+
+  const manifestPath = join(dir, "manifest.json");
+  const manifest: CaptureEntry[] = existsSync(manifestPath)
+    ? (JSON.parse(readFileSync(manifestPath, "utf8")) as CaptureEntry[])
+    : [];
+
+  const entries: CaptureEntry[] = [];
+  for (const vendor of config.vendors) {
+    const targets: Array<{ kind: CaptureEntry["kind"]; url: string }> = [
+      { kind: "home", url: vendor.urls.home },
+    ];
+    if (vendor.urls.pricing) targets.push({ kind: "pricing", url: vendor.urls.pricing });
+    for (const url of vendor.urls.product) targets.push({ kind: "product", url });
+
+    for (const target of targets) {
+      let status: number | null = null;
+      let text = "";
+      try {
+        const page = await fetchPage(target.url);
+        status = page.status;
+        if (page.status === 200) text = extractReadableText(page.body);
+      } catch {
+        status = null;
+      }
+      let captureHash: string | null = null;
+      if (text) {
+        captureHash = createHash("sha256").update(text).digest("hex");
+        // Content-addressed: an unchanged page dedupes to the same file.
+        writeFileSync(join(dir, `${captureHash}.txt`), text);
+      }
+      const entry: CaptureEntry = {
+        runLabel,
+        vendorId: vendor.id,
+        kind: target.kind,
+        url: target.url,
+        fetchedAt,
+        httpStatus: status,
+        captureHash,
+        textChars: text.length,
+      };
+      manifest.push(entry);
+      entries.push(entry);
+    }
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return { entries, manifestPath };
+}
+
+// ---------------------------------------------------------------------------
+// Observation store: append-only sets, one JSON file per run. Like the plan
+// store, this file layout and the hosted backend are two implementations of
+// the same contract.
+
+export interface ObservationStore {
+  append(set: ObservationSet): Promise<ObservationSet>;
+  get(runLabel: string): Promise<ObservationSet | null>;
+  list(): Promise<Array<{ runLabel: string; runAt: string; observations: number }>>;
+  latest(): Promise<ObservationSet | null>;
+}
+
+export function createFileObservationStore(category: string, directory?: string): ObservationStore {
+  const dir = directory ?? join(marketHome(category), "observations");
+
+  function fileFor(runLabel: string) {
+    if (!/^[\w.-]+$/.test(runLabel)) throw new Error(`Invalid run label: ${runLabel}`);
+    return join(dir, `${runLabel}.json`);
+  }
+
+  function read(runLabel: string): ObservationSet | null {
+    try {
+      return JSON.parse(readFileSync(fileFor(runLabel), "utf8")) as ObservationSet;
+    } catch {
+      return null;
+    }
+  }
+
+  function listSets(): ObservationSet[] {
+    let names: string[] = [];
+    try {
+      names = readdirSync(dir).filter((name) => name.endsWith(".json"));
+    } catch {
+      return [];
+    }
+    return names
+      .map((name) => read(name.replace(/\.json$/, "")))
+      .filter((set): set is ObservationSet => set !== null)
+      .sort((a, b) => a.runAt.localeCompare(b.runAt));
+  }
+
+  return {
+    async append(set) {
+      if (set.category !== category) {
+        throw new Error(`Observation set category "${set.category}" does not match store "${category}"`);
+      }
+      if (read(set.runLabel)) {
+        throw new Error(`Run "${set.runLabel}" already exists — observations are append-only; use a new run label`);
+      }
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(fileFor(set.runLabel), `${JSON.stringify(set, null, 2)}\n`);
+      return set;
+    },
+    async get(runLabel) {
+      return read(runLabel);
+    },
+    async list() {
+      return listSets().map((set) => ({
+        runLabel: set.runLabel,
+        runAt: set.runAt,
+        observations: set.observations.length,
+      }));
+    },
+    async latest() {
+      const sets = listSets();
+      return sets.length ? sets[sets.length - 1] : null;
+    },
+  };
+}
+
+/**
+ * Validate a proposed observation set against the config before it enters
+ * the store: known vendors/claims, full coverage, legal readings, and the
+ * verbatim-evidence rule (non-absent readings must quote something).
+ * Returns problems; an empty array means accept.
+ */
+export function validateObservationSet(config: MarketConfig, set: ObservationSet): string[] {
+  const problems: string[] = [];
+  const vendorIds = new Set(config.vendors.map((v) => v.id));
+  const claimIds = new Set(config.claims.map((c) => c.id));
+  const seen = new Set<string>();
+  for (const obs of set.observations) {
+    const cell = `${obs.vendorId} × ${obs.claimId}`;
+    if (!vendorIds.has(obs.vendorId)) problems.push(`unknown vendor "${obs.vendorId}"`);
+    if (!claimIds.has(obs.claimId)) problems.push(`unknown claim "${obs.claimId}"`);
+    if (seen.has(cell)) problems.push(`duplicate observation for ${cell}`);
+    seen.add(cell);
+    if (!INTENSITY_RANK[obs.intensity] && obs.intensity !== "unobservable") {
+      problems.push(`${cell}: invalid intensity "${obs.intensity}"`);
+    }
+    if ((obs.intensity === "loud" || obs.intensity === "quiet") && obs.evidence.length === 0) {
+      problems.push(`${cell}: ${obs.intensity} reading with no quoted evidence`);
+    }
+  }
+  for (const vendor of config.vendors) {
+    for (const claim of config.claims) {
+      if (!seen.has(`${vendor.id} × ${claim.id}`)) {
+        problems.push(`missing observation for ${vendor.id} × ${claim.id}`);
+      }
+    }
+  }
+  return problems;
+}
+
+// ---------------------------------------------------------------------------
+// Front states — deterministic, recomputed every time, never stored.
+
+export type ClaimFront = {
+  claimId: string;
+  state: FrontState;
+  loudVendorIds: string[];
+  quietVendorIds: string[];
+};
+
+/**
+ * Front rule v1: 0 loud → open (if anyone is quiet) or vacant; 1 loud →
+ * owned; 2–3 loud → contested; ≥4 loud → saturated. Unobservable cells are
+ * excluded — a failed capture never reads as absence.
+ */
+export function computeFrontStates(config: MarketConfig, set: ObservationSet): ClaimFront[] {
+  const byCell = new Map<string, MarketObservation>();
+  for (const obs of set.observations) {
+    const key = `${obs.vendorId}|${obs.claimId}`;
+    const existing = byCell.get(key);
+    if (!existing || INTENSITY_RANK[obs.intensity] > INTENSITY_RANK[existing.intensity]) {
+      byCell.set(key, obs);
+    }
+  }
+  return config.claims.map((claim) => {
+    const loud: string[] = [];
+    const quiet: string[] = [];
+    for (const vendor of config.vendors) {
+      const obs = byCell.get(`${vendor.id}|${claim.id}`);
+      if (obs?.intensity === "loud") loud.push(vendor.id);
+      if (obs?.intensity === "quiet") quiet.push(vendor.id);
+    }
+    let state: FrontState;
+    if (loud.length === 0) state = quiet.length >= 1 ? "open" : "vacant";
+    else if (loud.length === 1) state = "owned";
+    else if (loud.length <= 3) state = "contested";
+    else state = "saturated";
+    return { claimId: claim.id, state, loudVendorIds: loud, quietVendorIds: quiet };
+  });
+}
+
+export type FrontDrift = {
+  claimId: string;
+  before: FrontState;
+  after: FrontState;
+};
+
+/** What changed in the category between two runs — the refresh's whole point. */
+export function diffFrontStates(before: ClaimFront[], after: ClaimFront[]): FrontDrift[] {
+  const prior = new Map(before.map((front) => [front.claimId, front.state]));
+  const drift: FrontDrift[] = [];
+  for (const front of after) {
+    const was = prior.get(front.claimId);
+    if (was && was !== front.state) drift.push({ claimId: front.claimId, before: was, after: front.state });
+  }
+  return drift;
+}