fullstackgtm 0.17.0 → 0.19.0

package/dist/marketReport.js

@@ -1,4 +1,5 @@
 import { computeFrontStates } from "./market.js";
+import { assessAxes, messageBreadth } from "./marketAxes.js";
 /**
  * Render a market map as a client-ready deliverable: markdown for terminals
  * and PRs, and a self-contained printable HTML "field report" — front
@@ -77,6 +78,107 @@ export function marketMapToMarkdown(config, set) {
     }
     return `${lines.join("\n")}\n`;
 }
+function svgScatter(points, ax, ay, anchor, mini) {
+    const W = mini ? 330 : 700;
+    const H = mini ? 250 : 460;
+    const PAD = mini ? 34 : 56;
+    const range = (axis, values) => {
+        if (axis.signed)
+            return [-1.1, 1.1];
+        if (values.length === 0)
+            return [0, 1];
+        return [Math.min(0, Math.min(...values) - 0.05), Math.max(...values) + 0.08];
+    };
+    const [xLo, xHi] = range(ax, points.map((p) => p.x));
+    const [yLo, yHi] = range(ay, points.map((p) => p.y));
+    const sx = (x) => PAD + ((x - xLo) / (xHi - xLo)) * (W - 2 * PAD);
+    const sy = (y) => H - PAD - ((y - yLo) / (yHi - yLo)) * (H - 2 * PAD);
+    const fsLabel = mini ? 8.5 : 10.5;
+    const fsAx = mini ? 8 : 10;
+    const e = escapeHtml;
+    const dots = points
+        .map((p) => {
+        const r = mini ? 3 + p.loud * 0.8 : 6 + p.loud * 1.6;
+        const cls = p.vendorId === anchor ? "dot-anchor" : "dot";
+        return (`<circle class="${cls}" cx="${sx(p.x).toFixed(1)}" cy="${sy(p.y).toFixed(1)}" r="${r.toFixed(1)}"/>` +
+            `<text class="dot-label" style="font-size:${fsLabel}px" x="${sx(p.x).toFixed(1)}" y="${(sy(p.y) - r - 4).toFixed(1)}">${e(p.name)}</text>`);
+    })
+        .join("");
+    const midX = ax.signed ? `<line class="axis-mid" x1="${sx(0).toFixed(0)}" y1="${PAD}" x2="${sx(0).toFixed(0)}" y2="${H - PAD}"/>` : "";
+    const midY = ay.signed ? `<line class="axis-mid" x1="${PAD}" y1="${sy(0).toFixed(0)}" x2="${W - PAD}" y2="${sy(0).toFixed(0)}"/>` : "";
+    return `<svg viewBox="0 0 ${W} ${H}" role="img" aria-label="${e(ax.label)} vs ${e(ay.label)}">
+    <line class="axis" x1="${PAD}" y1="${H - PAD}" x2="${W - PAD}" y2="${H - PAD}"/>
+    <line class="axis" x1="${PAD}" y1="${PAD}" x2="${PAD}" y2="${H - PAD}"/>${midX}${midY}
+    <text class="ax-label" style="font-size:${fsAx}px" x="${PAD}" y="${H - 14}">&#8592; ${e(ax.negativePole)}</text>
+    <text class="ax-label" style="font-size:${fsAx}px" x="${W - PAD}" y="${H - 14}" text-anchor="end">${e(ax.positivePole)} &#8594;</text>
+    <text class="ax-label" style="font-size:${fsAx}px" x="${PAD}" y="${PAD - 10}">&#8593; ${e(ay.positivePole)}${ay.signed ? ` &#183; &#8595; ${e(ay.negativePole)}` : ""}</text>
+    ${dots}</svg>`;
+}
+function axisSectionsHtml(config, set) {
+    const axes = config.axes ?? [];
+    if (axes.length === 0)
+        return { strategicMap: "", report: null };
+    const e = escapeHtml;
+    const report = assessAxes(config, set);
+    const vendorNames = new Map(config.vendors.map((vendor) => [vendor.id, vendor.name]));
+    const loudCounts = new Map(report.vendors.map((vendorId) => [vendorId, messageBreadth(vendorId, set.observations).loudCount]));
+    const breadthAxis = {
+        id: "breadth",
+        label: "Message breadth",
+        negativePole: "FOCUSED",
+        positivePole: "BROAD (share of claims voiced)",
+        signed: false,
+    };
+    const axisInfo = new Map([
+        ...axes.map((axis) => [axis.id, { id: axis.id, label: axis.label, negativePole: axis.negativePole, positivePole: axis.positivePole, signed: true }]),
+        [breadthAxis.id, breadthAxis],
+    ]);
+    const positions = new Map();
+    for (const assessment of report.assessments) {
+        positions.set(assessment.axis.id, new Map(assessment.positions
+            .filter((entry) => entry.position !== null)
+            .map((entry) => [entry.vendorId, entry.position])));
+    }
+    const breadthMap = new Map();
+    for (const vendorId of report.vendors) {
+        const { breadth } = messageBreadth(vendorId, set.observations);
+        if (breadth !== null)
+            breadthMap.set(vendorId, breadth);
+    }
+    positions.set("breadth", breadthMap);
+    const pointsFor = (xId, yId) => {
+        const xs = positions.get(xId);
+        const ys = positions.get(yId);
+        if (!xs || !ys)
+            return [];
+        return report.vendors
+            .filter((vendorId) => xs.has(vendorId) && ys.has(vendorId))
+            .map((vendorId) => ({
+            vendorId,
+            name: vendorNames.get(vendorId) ?? vendorId,
+            x: xs.get(vendorId),
+            y: ys.get(vendorId),
+            loud: loudCounts.get(vendorId) ?? 0,
+        }));
+    };
+    const [px, py] = config.primaryAxes ?? [axes[0].id, axes[1]?.id ?? "breadth"];
+    const axInfo = axisInfo.get(px);
+    const ayInfo = axisInfo.get(py);
+    const statusOf = (id) => axes.find((axis) => axis.id === id)?.status ?? (id === "breadth" ? "derived" : "");
+    const strategicMap = `<section>
+  <h2><span class="no">03</span> Strategic map — ${e(axInfo.label)} &#215; ${e(ayInfo.label)}</h2>
+  <figure>${svgScatter(pointsFor(px, py), axInfo, ayInfo, config.anchorVendor, false)}
+  <figcaption>Positions computed from run ${e(set.runLabel)} observations: each axis is a per-claim scoring rubric
+  in the market config; a vendor sits at the intensity-weighted mean (loud=1, quiet=&#189;) of the claims it
+  voices. Dot size = LOUD count. Axis status — ${e(axInfo.label)}: ${e(statusOf(px))}; ${e(ayInfo.label)}: ${e(statusOf(py))}.</figcaption>
+  </figure>
+</section>`;
+    // Deliberately no axis-pairing gallery here: the report is the client-facing
+    // artifact, best foot forward — one earned 2x2. Axis exploration (PCA,
+    // triangulation, the orthogonality screen over every pairing) lives in
+    // `market axes` for the analyst or agent doing the iterating.
+    return { strategicMap, report };
+}
 export function marketMapToHtml(config, set) {
     const model = buildModel(config, set);
     const stateByClaim = new Map(model.fronts.map((front) => [front.claimId, front.state]));
@@ -87,6 +189,8 @@ export function marketMapToHtml(config, set) {
     const unobservable = set.observations.filter((obs) => obs.intensity === "unobservable").length;
     const anchor = config.anchorVendor;
     const e = escapeHtml;
+    const axisHtml = axisSectionsHtml(config, set);
+    const appendixNo = axisHtml.report ? "04" : "03";
     const matrixRows = model.orderedClaimIds
         .map((claimId) => {
         const claim = claimsById.get(claimId);
@@ -184,6 +288,14 @@ tr.front-open th .claim-cap { color:var(--accent); font-weight:600; }
 .ev-head { font-size:10.5px; letter-spacing:.1em; color:var(--accent); }
 .ev blockquote { font-style:italic; margin:6px 0; font-size:13.5px; line-height:1.5; }
 .ev-src { font-size:10px; color:var(--ink-soft); word-break:break-all; }
+figure { margin-top:22px; border:1px solid var(--line); background:rgba(255,255,255,.35); }
+.axis { stroke:var(--ink); stroke-width:1.5; }
+.axis-mid { stroke:var(--line); stroke-dasharray:3 5; }
+.ax-label { letter-spacing:.16em; fill:var(--ink-soft); font-family:"SF Mono",Menlo,Consolas,monospace; }
+.dot { fill:rgba(33,29,22,.78); }
+.dot-anchor { fill:var(--green); stroke:var(--ink); stroke-width:1.5; }
+.dot-label { fill:var(--ink); text-anchor:middle; letter-spacing:.04em; font-family:"SF Mono",Menlo,Consolas,monospace; }
+figcaption { font-size:12px; color:var(--ink-soft); padding:12px 16px 14px; font-style:italic; border-top:1px solid var(--line); line-height:1.5; }
 footer { margin-top:72px; border-top:3px double var(--ink); padding-top:14px; font-size:11px; color:var(--ink-soft);
   display:flex; justify-content:space-between; gap:20px; flex-wrap:wrap; }
 @media print { body { max-width:none; padding:0 8mm; background:white; } section { break-inside:avoid-page; } tr { break-inside:avoid; } }
@@ -221,8 +333,9 @@ footer { margin-top:72px; border-top:3px double var(--ink); padding-top:14px; fo
     <tbody>${matrixRows}</tbody>
   </table>
 </section>
+${axisHtml.strategicMap}
 <section>
-  <h2><span class="no">03</span> Evidence appendix</h2>
+  <h2><span class="no">${appendixNo}</span> Evidence appendix</h2>
   ${appendix}
 </section>
 <footer>

package/dist/mcp.js

@@ -260,7 +260,7 @@ export async function startMcpServer() {
             captureRun: z.string().optional(),
         },
     }, async ({ vendorId, configPath, captureRun }) => {
-        const config = loadMarketConfig(resolve(process.cwd(), configPath ?? "market.config.json"));
+        const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
         return content(buildWorksheet(config, vendorId, { captureRun }));
     });
     server.registerTool("fullstackgtm_market_observe", {
@@ -274,7 +274,7 @@ export async function startMcpServer() {
             configPath: z.string().optional().describe("Path to market.config.json (default ./market.config.json)"),
         },
     }, async ({ observationsPath, configPath }) => {
-        const config = loadMarketConfig(resolve(process.cwd(), configPath ?? "market.config.json"));
+        const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
         const set = JSON.parse(readFileSync(resolve(process.cwd(), observationsPath), "utf8"));
         const problems = validateObservationSet(config, set);
         const failures = verifyEvidenceSpans(set.observations, loadCaptureTexts(config.category).textByHash);
@@ -292,3 +292,14 @@ export async function startMcpServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+function loadMarketConfigOrHint(path) {
+    try {
+        return loadMarketConfig(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`No market config at ${path} — run \`fullstackgtm market init --category <name>\` in that directory first, or pass configPath.`);
+        }
+        throw error;
+    }
+}

package/dist/types.d.ts

@@ -222,6 +222,23 @@ export type PatchOperation = {
     evidenceIds?: string[];
     findingIds?: string[];
     verification?: PatchVerification;
+    /**
+     * Compare-and-set guards beyond the written field: each precondition is
+     * re-read at apply time and a mismatch turns the operation into a
+     * conflict instead of a write. Guards against a record drifting on a
+     * DIFFERENT field than the one being written (e.g. stage changed while
+     * an owner write was pending).
+     */
+    preconditions?: Array<{
+        field: string;
+        expectedValue: unknown;
+    }>;
+    /**
+     * Operations sharing a groupId are all-or-nothing at apply time: a
+     * conflict (beforeValue or precondition) on any member skips every
+     * member of the group.
+     */
+    groupId?: string;
 };
 /**
  * A patch plan is always a dry-run proposal. Applying a plan never mutates
@@ -238,6 +255,33 @@ export type PatchPlan = {
     pipelineFindings?: PipelineFinding[];
     evidence?: GtmEvidence[];
     operations: PatchOperation[];
+    /**
+     * The filter this plan's operations were selected by. Re-evaluated per
+     * record against a FRESH snapshot at apply time: any operation whose
+     * record no longer matches is reported as a conflict instead of applied.
+     * Unlike per-operation preconditions, this enforces the FULL filter —
+     * negations and relational pseudo-fields included.
+     */
+    filter?: {
+        objectType: "account" | "contact" | "deal";
+        where: string[];
+    };
+    /**
+     * Plan-level guards re-evaluated against a FRESH snapshot at apply time.
+     * If any guard fails, NO operation in the plan is applied. This is how a
+     * plan expresses cross-record eligibility ("apply only while the account
+     * still has no open deal in contractsent") that per-operation
+     * preconditions cannot reach.
+     */
+    guards?: PlanGuard[];
+};
+export type PlanGuard = {
+    objectType: "account" | "contact" | "deal";
+    /** filter expressions in bulk-update --where grammar, AND-ed */
+    where: string[];
+    /** none: guard passes when ZERO records match; some: when at least one matches */
+    expect: "none" | "some";
+    description?: string;
 };
 /** Pre-computed lookups shared by all rules so each rule stays O(n). */
 export type GtmSnapshotIndex = {

package/docs/api.md

@@ -58,7 +58,9 @@ release.
 ## CLI
 
 Commands: `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `plans`,
-`apply`, `rules`, `profiles`, `doctor`.
+`apply`, `suggest`, `call` (`parse` / `score` / `link` / `plan`), `resolve`,
+`market` (`init` / `capture` / `classify` / `worksheet` / `observe` / `fronts` /
+`axes` / `report` / `refresh`), `rules`, `profiles`, `doctor`.
 Exit codes: `0` success · `1` error · `2` findings/regressions at the requested gate
 (`--fail-on`, `--fail-on-new-findings`). `--json` everywhere; JSON output shapes are stable.
 
@@ -78,7 +80,32 @@ deliverable in markdown or self-contained HTML: severity counts, prose summary,
 per-rule detail with capped examples, and next steps. `auditReportToMarkdown` /
 `auditReportToHtml` expose the same rendering programmatically.
 
+## Market map
+
+Newer surface (0.16–0.18); shapes are settling toward the 1.0 contract. A live
+model of the competitive category: claim taxonomy + vendor registry as a
+reviewable `market.config.json` (`MarketConfig`, `MarketClaim`, `MarketVendor`,
+`MarketAxis`), content-addressed page captures (`captureMarket`,
+`loadCaptureTexts`), append-only observations (`ObservationSet`,
+`MarketObservation`, `ObservationStore` / `createFileObservationStore` —
+profile-scoped under `<home>/market/<category>`), and deterministic
+derivations: `computeFrontStates` / `diffFrontStates` (front rule v1),
+`assessAxes` / `pcaTop2` / `axisPosition` (axis discovery), and
+`marketMapToMarkdown` / `marketMapToHtml` (the field report; renders the
+primary strategic 2×2 when `axes` / `primaryAxes` are configured).
+
+Intensity readings are proposals: `classifyMarket` (LLM, bring-your-own-key,
+provenance-marked) or `buildWorksheet` + `market observe` (agent/human). Every
+quoted evidence span is mechanically verified verbatim
+(`verifyEvidenceSpans`; whitespace and punctuation-spacing normalized) against
+the stored capture it cites before a set is accepted; failed captures read as
+`unobservable`, never `absent`.
+
 ## MCP
 
 Tools: `fullstackgtm_audit`, `fullstackgtm_rules`, `fullstackgtm_apply`
-(requires explicit `approvedOperationIds`). Input schemas are stable.
+(requires explicit `approvedOperationIds`), `fullstackgtm_suggest`,
+`fullstackgtm_call_parse`, `fullstackgtm_resolve`,
+`fullstackgtm_market_worksheet`, `fullstackgtm_market_observe` (validates,
+verifies quoted spans against the stored captures, appends, returns front
+states). Input schemas are stable.

package/llms.txt

@@ -31,6 +31,22 @@ coaching scorecards; `call link` suggests the deal with confidence + reason;
 `call plan` proposes governed next-step writes through the standard
 approve/apply lifecycle.
 
+## Key invariants (market map)
+
+`fullstackgtm market` models the competitive category: vendors + claim
+taxonomy in `market.config.json`; `capture` stores vendor pages
+content-addressed; `classify` (BYO key, same ladder as calls) or
+`worksheet` + `observe` (agent/human channel) propose LOUD/QUIET/ABSENT
+intensity readings per vendor × claim. Every quoted evidence span is
+mechanically verified verbatim against the stored capture it cites;
+unverifiable quotes are rejected (`--unverified` only when captures live
+elsewhere). Failed captures read UNOBSERVABLE, never ABSENT. `fronts --diff`
+= deterministic front states + drift between runs; `axes` = PCA axis
+discovery + orthogonality screen; `report` = self-contained HTML field
+report; `refresh` = capture → classify → drift → report in one command.
+Storage is profile-scoped under `<home>/market/<category>`. MCP:
+`fullstackgtm_market_worksheet`, `fullstackgtm_market_observe`.
+
 ## Key invariants
 
 - Reads are safe by default; nothing is written without explicit `--approve`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",