fullstackgtm 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,90 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.17.0] — 2026-06-11
+
+Market map classification: intensity readings become a one-command step, and
+the verbatim-quote rule becomes a mechanical gate instead of a prompt
+instruction.
+
+### Added
+
+- **`fullstackgtm market classify`** — LLM intensity readings for every
+  vendor × claim cell from the stored captures, through the same
+  bring-your-own-key constrained-tool-call seam as `call parse`
+  (provenance `extractor: "llm:<provider>:<model>"`). Vendors with no
+  usable captures score UNOBSERVABLE deterministically, without an LLM
+  call. `--vendor` classifies one vendor to `--out` for hand-merging;
+  `--model` overrides the provider default.
+- **Mechanical span verification** — because market sources are *stored*
+  captures (unlike transcripts, which pass through), every quoted evidence
+  span is checked character-for-character (whitespace-normalized) against
+  the capture it cites. Readings that fail bounce back to the model once
+  with the failures named; persistent failures abort with nothing stored.
+  The same gate now guards `market observe` (escape hatch: `--unverified`,
+  for sets whose captures genuinely live elsewhere) and the MCP submission
+  path — every proposal channel passes the same gate.
+- **`fullstackgtm market worksheet --vendor <id>`** — the no-key channel:
+  a self-contained packet (claims with judging definitions, surface rule,
+  captured page texts) for an agent or human to classify by hand and
+  submit via `observe`.
+- **`fullstackgtm market refresh`** — capture → classify → front drift →
+  HTML field report, one command. The weekly refresh is now a single
+  invocation (schedule it however you schedule things).
+- **MCP**: `fullstackgtm_market_worksheet` and `fullstackgtm_market_observe`
+  (validates + verifies + appends; returns the computed front states on
+  acceptance).
+- `forcedToolCall` exported from `llm.ts` — the one seam every LLM feature
+  in the package goes through.
+
+## [0.16.0] — 2026-06-11
+
+The market map: a live model of the competitive category a company sells
+into — claim taxonomy as reviewable config, append-only observations with
+verbatim-quote evidence, deterministic front states and drift.
+
+### Added
+
+- **`fullstackgtm market`** — `init` scaffolds a `market.config.json`
+  (vendor registry + claim taxonomy + the LOUD/QUIET/ABSENT surface rule);
+  `capture` fetches vendor pages into a content-addressed text cache (the
+  change detector, replay buffer, and evidence chain); `observe --from`
+  ingests intensity readings after validating full coverage and the
+  verbatim-evidence rule (a loud/quiet reading with no quote is rejected);
+  `fronts` computes deterministic front states (open / contested / owned /
+  saturated / vacant) and `--diff` reports drift between runs; `report`
+  renders the claim × vendor matrix as markdown or a self-contained
+  printable HTML field report with an evidence appendix.
+- **Division of labor matches call intelligence:** intensity readings are
+  proposals (provenance-marked extractor, always with quoted evidence);
+  everything downstream is deterministic over the stored observations —
+  same observations, same map. A failed capture reads as UNOBSERVABLE,
+  never as absence.
+- **Profile-scoped storage:** captures and observations live under
+  `~/.fullstackgtm/market/<category>` (or the active profile's home), so one
+  client org's category intel never bleeds into another's.
+- `ObservationStore` contract + file implementation (append-only, one JSON
+  document per run) — like the plan store, the file layout and the hosted
+  backend are two implementations of the same contract.
+- `"web"` joined `GtmEvidenceSourceSystem`: market observations carry
+  standard `GtmEvidence` with `metadata.url` + `metadata.captureHash`.
+
+## [0.15.1] — 2026-06-11
+
+Fixes from the 0.15.0 journey verification (4 agents, 26 checks).
+
+### Fixed
+
+- **Name-only deal resolution is gated**: `resolve deal --name X` without
+  `--account-id` returned safe_to_create even when open deals named X
+  existed — a gate that ignores name collisions protects nobody. It now
+  returns ambiguous with the colliding open deals and tells the caller to
+  supply `--account-id` for a definitive answer.
+- The closed-deals-share-name note is account-scoped (it previously counted
+  closed deals on *other* accounts).
+- The `hs_object_source_detail_2` stamp on CLI-created companies now
+  carries the operation id for precise attribution.
+
 ## [0.15.0] — 2026-06-11
 
 The Prevent layer: stop creating duplicates, and name the writer that does.

package/dist/cli.js

@@ -18,6 +18,9 @@ import { auditReportToHtml, auditReportToMarkdown } from "./report.js";
 import { builtinAuditRules } from "./rules.js";
 import { sampleSnapshot } from "./sampleData.js";
 import { normalizeTranscript, parseCall, suggestCallDeal } from "./calls.js";
+import { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, loadCaptureTexts, loadMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
+import { buildWorksheet, classifyMarket } from "./marketClassify.js";
+import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 import { DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 import { resolveRecord } from "./resolve.js";
 import { suggestValues } from "./suggest.js";
@@ -55,6 +58,20 @@ 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 classify [--run <label>] [--vendor <id>] [--model m] [--out <path>]
+  fullstackgtm market worksheet --vendor <id> [--out <path>]
+  fullstackgtm market observe --from <observations.json> [--unverified]
+  fullstackgtm market fronts [--run <label>] [--diff <prior-run>] [--json]
+  fullstackgtm market report [--run <label>] [--format md|html] [--out <path>]
+  fullstackgtm market refresh [--run <label>] [--model m]
+                                               the live competitive map: capture vendor pages (content-addressed),
+                                               classify intensity per claim (LLM bring-your-own-key, or fill the
+                                               worksheet with any agent) — every quoted span is verified verbatim
+                                               against the stored capture it cites before it's accepted — then
+                                               compute deterministic front states and drift, render the field
+                                               report. refresh = capture → classify → drift → report in one step
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -606,9 +623,14 @@ async function requireLlmCredential(command = "parse") {
     if (resolved)
         return resolved;
     // Scoring is inherently LLM work — there is no keyword fallback to suggest.
-    const fallbackHint = command === "parse" ? ", or pass --deterministic for the free keyword baseline" : " (call score has no non-LLM mode)";
+    const fallbackHint = command === "parse"
+        ? ", or pass --deterministic for the free keyword baseline"
+        : command === "score"
+            ? " (call score has no non-LLM mode)"
+            : ", or classify by hand: `market worksheet --vendor <id>` then `market observe --from`";
+    const work = command === "score" ? "scoring" : command === "parse" ? "extraction" : "classification";
     if (!process.stdin.isTTY) {
-        throw new Error(`LLM ${command === "score" ? "scoring" : "extraction"} needs an API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or run \`echo "$KEY" | fullstackgtm login anthropic\` (or \`login openai\`) once${fallbackHint}.`);
+        throw new Error(`LLM ${work} needs an API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or run \`echo "$KEY" | fullstackgtm login anthropic\` (or \`login openai\`) once${fallbackHint}.`);
     }
     console.error("LLM parsing needs an API key (Anthropic or OpenAI) — yours, used directly with the provider.");
     console.error(`Paste it once; it is validated and stored at ${credentialsPath()} (file mode 0600), like CRM logins.`);
@@ -715,6 +737,218 @@ function buildCallPlan(parsed, deal, proposed, current, extraNextSteps) {
         operations,
     };
 }
+/**
+ * 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. Intensity readings enter as
+ * proposals through two channels — `classify` (LLM, bring-your-own-key, the
+ * call-intelligence pattern) and `worksheet`/`observe` (an agent or human
+ * fills the worksheet) — and BOTH pass the same mechanical gate: every quoted
+ * span is verified verbatim against the stored capture it cites.
+ */
+async function marketCommand(args) {
+    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 classify [--run <label>] [--capture-run <label>] [--vendor <id>] [--model m] [--out <path>]
+market worksheet --vendor <id> [--capture-run <label>] [--out <path>]
+market observe --from <observations.json> [--unverified]
+market fronts [--config <path>] [--run <label>] [--diff <prior-run>] [--json]
+market report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
+market refresh [--run <label>] [--model m]     capture → classify → fronts drift → HTML report
+
+classify uses your Anthropic/OpenAI key (like call parse) to read the stored
+captures and propose intensity readings; worksheet is the no-key path (an
+agent or human fills it, submits via observe). Either way, every quoted span
+is verified character-for-character against the capture it cites before the
+observation is accepted — quotes that aren't on the page bounce.
+
+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"));
+        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;
+        }
+        if (!rest.includes("--unverified")) {
+            const { textByHash } = loadCaptureTexts(config.category);
+            const failures = verifyEvidenceSpans(set.observations, textByHash);
+            if (failures.length > 0) {
+                console.error(`Rejected: ${failures.length} evidence span(s) failed verification against the stored captures`);
+                for (const failure of failures.slice(0, 20)) {
+                    console.error(`  - ${failure.vendorId} × ${failure.claimId}: ${failure.problem}`);
+                }
+                console.error("Quotes must be copied verbatim from the captured pages. (--unverified skips this gate when the captures genuinely live elsewhere.)");
+                process.exitCode = 1;
+                return;
+            }
+        }
+        await store.append(set);
+        console.log(`Appended ${set.runLabel}: ${set.observations.length} observations (${set.extractor})`);
+        return;
+    }
+    if (subcommand === "worksheet") {
+        const vendorId = option(rest, "--vendor");
+        if (!vendorId)
+            throw new Error("market worksheet requires --vendor <id>");
+        const worksheet = buildWorksheet(config, vendorId, { captureRun: option(rest, "--capture-run") ?? undefined });
+        const outPath = option(rest, "--out");
+        const payload = `${JSON.stringify(worksheet, null, 2)}\n`;
+        if (outPath) {
+            writeFileSync(resolve(process.cwd(), outPath), payload);
+            console.log(`Wrote ${outPath} (${worksheet.pages.length} captured pages, ${worksheet.claims.length} claims)`);
+        }
+        else {
+            console.log(payload);
+        }
+        return;
+    }
+    if (subcommand === "classify") {
+        const credential = await requireLlmCredential("market classify");
+        const vendorFilter = option(rest, "--vendor");
+        const outPath = option(rest, "--out");
+        if (vendorFilter && !outPath) {
+            throw new Error("market classify --vendor produces a partial set (coverage validation would reject it) — pass --out <path> to inspect/merge it by hand");
+        }
+        const result = await classifyMarket(config, {
+            llm: { ...credential, model: option(rest, "--model") ?? undefined },
+            runLabel: option(rest, "--run") ?? option(rest, "--capture-run") ?? "run-1",
+            captureRun: option(rest, "--capture-run") ?? undefined,
+            vendors: vendorFilter ? [vendorFilter] : undefined,
+        });
+        if (result.retriedVendorIds.length > 0) {
+            console.error(`Span verification bounced ${result.retriedVendorIds.join(", ")} once; retry passed.`);
+        }
+        if (outPath) {
+            writeFileSync(resolve(process.cwd(), outPath), `${JSON.stringify(result.set, null, 2)}\n`);
+            console.log(`Wrote ${outPath}: ${result.set.observations.length} verified observations (${result.set.extractor})`);
+            return;
+        }
+        const problems = validateObservationSet(config, result.set);
+        if (problems.length > 0) {
+            throw new Error(`Classified set failed validation: ${problems.slice(0, 5).join("; ")}`);
+        }
+        await store.append(result.set);
+        console.log(`Appended ${result.set.runLabel}: ${result.set.observations.length} observations, every span verified (${result.set.extractor})`);
+        return;
+    }
+    if (subcommand === "refresh") {
+        const credential = await requireLlmCredential("market classify");
+        const runLabel = option(rest, "--run") ?? `run-${new Date().toISOString().slice(0, 10)}`;
+        const prior = await store.latest();
+        console.log(`Capturing ${config.vendors.length} vendors as ${runLabel}…`);
+        const captured = await captureMarket(config, { runLabel });
+        const failed = captured.entries.filter((entry) => !entry.captureHash);
+        if (failed.length > 0)
+            console.log(`${failed.length} page(s) failed/empty — affected cells will verify against remaining pages or read unobservable.`);
+        console.log(`Classifying with ${credential.provider}…`);
+        const result = await classifyMarket(config, {
+            llm: { ...credential, model: option(rest, "--model") ?? undefined },
+            runLabel,
+            captureRun: runLabel,
+        });
+        await store.append(result.set);
+        const fronts = computeFrontStates(config, result.set);
+        if (prior) {
+            const drift = diffFrontStates(computeFrontStates(config, prior), fronts);
+            if (drift.length === 0)
+                console.log(`No front changes since ${prior.runLabel}.`);
+            for (const change of drift)
+                console.log(`CHANGED   ${change.claimId}: ${change.before} → ${change.after}`);
+        }
+        const outPath = option(rest, "--out") ?? `${config.category}-${runLabel}.html`;
+        writeFileSync(resolve(process.cwd(), outPath), marketMapToHtml(config, result.set));
+        console.log(`Wrote ${outPath}`);
+        return;
+    }
+    const loadSet = async () => {
+        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, classify, worksheet, observe, fronts, report, refresh)`);
+}
 /**
  * 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
@@ -1496,6 +1730,10 @@ export async function runCli(argv) {
         await resolveCommand(args);
         return;
     }
+    if (command === "market") {
+        await marketCommand(args);
+        return;
+    }
     if (command === "profiles") {
         profilesCommand(args);
         return;

package/dist/connectors/hubspot.js

@@ -334,7 +334,7 @@ export function createHubspotConnector(options) {
                         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})` },
                             }),
                         });
                     }

package/dist/index.d.ts

@@ -19,5 +19,8 @@ export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, s
 export { sampleSnapshot } from "./sampleData.ts";
 export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, type CallScorecard, type LlmCredential, type LlmExtractedInsight, type LlmProvider, type Rubric, type ScoredDimension, } from "./llm.ts";
 export { resolveRecord, type ResolveCandidate, type ResolveMatch, type ResolveResult } from "./resolve.ts";
+export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, 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, type SpanVerificationFailure, } from "./market.ts";
+export { buildWorksheet, classifyMarket, type ClassifyMarketOptions, type ClassifyMarketResult, type MarketWorksheet, } from "./marketClassify.ts";
+export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type { ApprovalStatus, AuditFinding, AuditFindingSeverity, CanonicalAccount, CanonicalActivity, CanonicalContact, CanonicalDeal, CanonicalGtmSnapshot, CanonicalUser, CrmProvider, GtmAuditRule, GtmConnector, GtmEvidence, GtmEvidenceSourceSystem, GtmObjectType, GtmPolicy, GtmRuleContext, GtmRuleResult, GtmSnapshotIndex, PatchOperation, PatchOperationResult, PatchOperationType, PatchPlan, PatchPlanRun, PatchPlanRunStatus, PatchVerification, PipelineFinding, PipelineFindingStatus, PipelineFindingType, ProviderIdentity, RiskLevel, SourceFreshness, } from "./types.ts";

package/dist/index.js

@@ -19,4 +19,7 @@ export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, s
 export { sampleSnapshot } from "./sampleData.js";
 export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 export { resolveRecord } from "./resolve.js";
+export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
+export { buildWorksheet, classifyMarket, } from "./marketClassify.js";
+export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 export { suggestValues } from "./suggest.js";

package/dist/llm.d.ts

@@ -64,6 +64,13 @@ export declare function scoreCallLlm(transcript: string, rubric: Rubric, options
     title?: string;
 }): Promise<CallScorecard>;
 export declare function parseRubric(json: string): Rubric;
+/**
+ * Shared constrained-tool-call plumbing: force the model to answer through a
+ * single tool whose input_schema is the output contract. Exported for other
+ * semi-deterministic features (market classification) — every LLM feature in
+ * the package goes through this one seam.
+ */
+export declare function forcedToolCall(prompt: string, toolName: string, schema: object, model: string, options: LlmCallOptions): Promise<unknown>;
 /** Cheap key validation against the provider's model-list endpoint. Status line only. */
 export declare function validateLlmKey(provider: LlmProvider, apiKey: string, fetchImpl?: typeof fetch): Promise<{
     ok: boolean;

package/dist/llm.js

@@ -158,7 +158,13 @@ export function parseRubric(json) {
     };
 }
 // ── Provider plumbing (raw fetch, forced tool calls) ───────────────────────
-async function forcedToolCall(prompt, toolName, schema, model, options) {
+/**
+ * Shared constrained-tool-call plumbing: force the model to answer through a
+ * single tool whose input_schema is the output contract. Exported for other
+ * semi-deterministic features (market classification) — every LLM feature in
+ * the package goes through this one seam.
+ */
+export async function forcedToolCall(prompt, toolName, schema, model, options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     if (options.provider === "anthropic") {
         const response = await llmFetch(fetchImpl, ANTHROPIC_URL, {

package/dist/market.d.ts

@@ -0,0 +1,166 @@
+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;
+};
+export declare function observationId(category: string, runLabel: string, vendorId: string, claimId: string): string;
+export declare function parseMarketConfig(raw: string): MarketConfig;
+export declare function loadMarketConfig(path: string): MarketConfig;
+export declare function starterMarketConfig(category: string): MarketConfig;
+export declare function marketHome(category: string, baseDir?: string): string;
+export declare function extractReadableText(html: string): string;
+export type FetchPage = (url: string) => Promise<{
+    status: number;
+    body: string;
+}>;
+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 declare function captureMarket(config: MarketConfig, options?: CaptureOptions): Promise<CaptureResult>;
+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 declare function createFileObservationStore(category: string, directory?: string): ObservationStore;
+/**
+ * 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 declare function validateObservationSet(config: MarketConfig, set: ObservationSet): string[];
+export declare function loadCaptureTexts(category: string, directory?: string): {
+    entries: CaptureEntry[];
+    textByHash: Map<string, string>;
+};
+/**
+ * Whitespace-only normalization for span matching, plus one extraction
+ * artifact: the HTML-to-text step can emit a line break before punctuation
+ * that follows an inline tag ("placements\n. Districts"), which no honest
+ * quoter would reproduce — so whitespace *before* punctuation is dropped
+ * too. Words, casing, and characters must still match the page exactly.
+ */
+export declare function normalizeForMatch(value: string): string;
+export type SpanVerificationFailure = {
+    vendorId: string;
+    claimId: string;
+    quote: string;
+    problem: string;
+};
+export declare function verifyEvidenceSpans(observations: MarketObservation[], textByHash: Map<string, string>): SpanVerificationFailure[];
+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 declare function computeFrontStates(config: MarketConfig, set: ObservationSet): ClaimFront[];
+export type FrontDrift = {
+    claimId: string;
+    before: FrontState;
+    after: FrontState;
+};
+/** What changed in the category between two runs — the refresh's whole point. */
+export declare function diffFrontStates(before: ClaimFront[], after: ClaimFront[]): FrontDrift[];