fullstackgtm 0.21.2 → 0.23.1

package/src/enrichApollo.ts

@@ -0,0 +1,250 @@
+import type { CanonicalGtmSnapshot } from "./types.ts";
+import type { EnrichObjectType, EnrichSourceRecord, EnrichWorkItem } from "./enrich.ts";
+
+/**
+ * Apollo source client for the enrich layer: raw fetch against Apollo's REST
+ * enrichment endpoints (people match, organization enrich), bring-your-own
+ * key (`login apollo`), no SDK.
+ *
+ * The one genuinely new HTTP behavior lives here and ONLY here: enrichment
+ * APIs rate-limit aggressively, so requests retry on 429 with capped
+ * exponential backoff (honoring Retry-After when present). The shared
+ * connector contract is deliberately untouched.
+ */
+
+const DEFAULT_API_BASE_URL = "https://api.apollo.io";
+const DEFAULT_MAX_RETRIES = 3;
+const BASE_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 8_000;
+
+export type ApolloClientOptions = {
+  getApiKey: () => string | Promise<string>;
+  apiBaseUrl?: string;
+  /** Injectable fetch for testing — tests must never hit the real Apollo API. */
+  fetchImpl?: typeof fetch;
+  /** Max retries after a 429 (default 3). */
+  maxRetries?: number;
+  /** Injectable sleep for testing backoff without waiting. */
+  sleep?: (ms: number) => Promise<void>;
+};
+
+export type ApolloClient = {
+  /** GET /api/v1/organizations/enrich?domain=… → response body, or null on no data. */
+  enrichOrganization(domain: string): Promise<Record<string, unknown> | null>;
+  /** POST /api/v1/people/match { email } → response body, or null on no data. */
+  matchPerson(email: string): Promise<Record<string, unknown> | null>;
+};
+
+const defaultSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+function retryDelayMs(response: Response, attempt: number): number {
+  const retryAfter = response.headers.get("Retry-After");
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, MAX_BACKOFF_MS);
+    const at = Date.parse(retryAfter);
+    if (Number.isFinite(at)) return Math.min(Math.max(at - Date.now(), 0), MAX_BACKOFF_MS);
+  }
+  return Math.min(BASE_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+}
+
+export function createApolloClient(options: ApolloClientOptions): ApolloClient {
+  const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const sleep = options.sleep ?? defaultSleep;
+
+  async function request(path: string, init: RequestInit = {}): Promise<Record<string, unknown> | null> {
+    const apiKey = await options.getApiKey();
+    for (let attempt = 0; ; attempt += 1) {
+      let response: Response;
+      try {
+        response = await fetchImpl(`${baseUrl}${path}`, {
+          ...init,
+          headers: {
+            "X-Api-Key": apiKey,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            ...(init.headers ?? {}),
+          },
+        });
+      } catch (error) {
+        const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+        throw new Error(`Cannot reach Apollo at ${baseUrl}${cause}. Check network access.`);
+      }
+      if (response.status === 429 && attempt < maxRetries) {
+        await sleep(retryDelayMs(response, attempt));
+        continue;
+      }
+      if (response.status === 404) return null;
+      if (!response.ok) {
+        const body = await response.text();
+        const exhausted = response.status === 429 ? ` (rate limited; ${maxRetries} retries exhausted)` : "";
+        throw new Error(`Apollo API error ${response.status}${exhausted}: ${body}`);
+      }
+      const text = await response.text();
+      return text ? (JSON.parse(text) as Record<string, unknown>) : null;
+    }
+  }
+
+  return {
+    async enrichOrganization(domain) {
+      return request(`/api/v1/organizations/enrich?domain=${encodeURIComponent(domain)}`, {
+        method: "GET",
+      });
+    },
+    async matchPerson(email) {
+      return request("/api/v1/people/match", {
+        method: "POST",
+        body: JSON.stringify({ email }),
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pull adapter: snapshot-driven keys in, normalized source records out.
+
+export type ApolloPullKey = {
+  objectType: EnrichObjectType;
+  /** "domain" for companies, "email" for contacts. */
+  key: "domain" | "email";
+  value: string;
+};
+
+export type ApolloPullResult = {
+  records: EnrichSourceRecord[];
+  /** Pull keys Apollo returned no data for. */
+  misses: ApolloPullKey[];
+};
+
+export type ApolloPullProgress = {
+  /** The pull key just processed — the run-store cursor value. */
+  lastKeyValue: string;
+  record?: EnrichSourceRecord;
+  miss?: ApolloPullKey;
+};
+
+export type ApolloPullOptions = {
+  /** Resume checkpoint: pull keys at or before this value are skipped. */
+  resumeAfter?: string | null;
+  /** Checkpoint callback after each pull key is processed. */
+  onProgress?: (progress: ApolloPullProgress) => void | Promise<void>;
+};
+
+function stringAt(payload: Record<string, unknown> | null | undefined, path: string[]): string | undefined {
+  let current: unknown = payload;
+  for (const segment of path) {
+    if (!current || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return typeof current === "string" && current ? current : undefined;
+}
+
+/**
+ * Pull keys for an append run: records of the requested types where at least
+ * one configured field is blank and the pull key (companies: domain,
+ * contacts: email) is present. Deduplicated — two CRM companies sharing a
+ * domain produce ONE Apollo call, and the matcher then reports the collision.
+ */
+export function apolloPullKeysForAppend(
+  snapshot: CanonicalGtmSnapshot,
+  objectTypes: EnrichObjectType[],
+  needsEnrichment: (objectType: EnrichObjectType, record: Record<string, unknown>) => boolean,
+): ApolloPullKey[] {
+  const keys: ApolloPullKey[] = [];
+  const seen = new Set<string>();
+  for (const objectType of objectTypes) {
+    const records = objectType === "company" ? snapshot.accounts : snapshot.contacts;
+    const keyName = objectType === "company" ? ("domain" as const) : ("email" as const);
+    for (const record of records) {
+      const value = ((record as unknown as Record<string, unknown>)[keyName] as string | undefined)?.trim();
+      if (!value) continue;
+      if (!needsEnrichment(objectType, record as unknown as Record<string, unknown>)) continue;
+      const dedupe = `${objectType}|${value.toLowerCase()}`;
+      if (seen.has(dedupe)) continue;
+      seen.add(dedupe);
+      keys.push({ objectType, key: keyName, value });
+    }
+  }
+  return keys;
+}
+
+/** Pull keys for a refresh run: the stale work set mapped back to pull keys. */
+export function apolloPullKeysForRefresh(
+  snapshot: CanonicalGtmSnapshot,
+  workSet: EnrichWorkItem[],
+): ApolloPullKey[] {
+  const keys: ApolloPullKey[] = [];
+  const seen = new Set<string>();
+  for (const item of workSet) {
+    const records = item.objectType === "company" ? snapshot.accounts : snapshot.contacts;
+    const record = records.find((entry) => entry.id === item.objectId);
+    if (!record) continue;
+    const keyName = item.objectType === "company" ? ("domain" as const) : ("email" as const);
+    const value = ((record as unknown as Record<string, unknown>)[keyName] as string | undefined)?.trim();
+    if (!value) continue;
+    const dedupe = `${item.objectType}|${value.toLowerCase()}`;
+    if (seen.has(dedupe)) continue;
+    seen.add(dedupe);
+    keys.push({ objectType: item.objectType, key: keyName, value });
+  }
+  return keys;
+}
+
+/**
+ * Execute the pull: one Apollo call per key, normalized into source records.
+ * Sequential on purpose (enrichment endpoints rate-limit aggressively); the
+ * 429 backoff lives in the client. `onProgress` checkpoints the run-store
+ * cursor after every key so an interrupted pull resumes instead of re-paying
+ * for completed lookups.
+ */
+export async function pullApolloRecords(
+  client: ApolloClient,
+  keys: ApolloPullKey[],
+  options: ApolloPullOptions = {},
+): Promise<ApolloPullResult> {
+  const records: EnrichSourceRecord[] = [];
+  const misses: ApolloPullKey[] = [];
+  // Resume: skip keys up to and including the checkpoint. An unknown
+  // checkpoint (snapshot changed since the interrupted run) restarts cleanly.
+  const resumeIndex = options.resumeAfter
+    ? keys.findIndex((key) => key.value === options.resumeAfter)
+    : -1;
+  for (const key of keys.slice(resumeIndex + 1)) {
+    let record: EnrichSourceRecord | undefined;
+    if (key.objectType === "company") {
+      const payload = await client.enrichOrganization(key.value);
+      const organization = payload?.organization as Record<string, unknown> | undefined;
+      if (organization) {
+        record = {
+          id: `apollo:org_${stringAt(payload, ["organization", "id"]) ?? key.value}`,
+          objectType: "company",
+          keys: {
+            domain: stringAt(payload, ["organization", "primary_domain"]) ?? key.value,
+            name: stringAt(payload, ["organization", "name"]),
+          },
+          payload: payload as Record<string, unknown>,
+        };
+      }
+    } else {
+      const payload = await client.matchPerson(key.value);
+      const person = payload?.person as Record<string, unknown> | undefined;
+      if (person) {
+        record = {
+          id: `apollo:person_${stringAt(payload, ["person", "id"]) ?? key.value}`,
+          objectType: "contact",
+          keys: {
+            email: stringAt(payload, ["person", "email"]) ?? key.value,
+            name: stringAt(payload, ["person", "name"]),
+          },
+          payload: payload as Record<string, unknown>,
+        };
+      }
+    }
+    if (record) records.push(record);
+    else misses.push(key);
+    await options.onProgress?.({ lastKeyValue: key.value, record, miss: record ? undefined : key });
+  }
+  return { records, misses };
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 export { auditSnapshot, defaultPolicy } from "./audit.ts";
-export { buildBulkUpdatePlan, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
+export { buildBulkUpdatePlan, isFilterableField, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
+export { buildDedupePlan, dedupeKey, type DedupeOptions } from "./dedupe.ts";
+export { buildReassignPlans, type ReassignObjectType, type ReassignOptions } from "./reassign.ts";
 export {
   CONFIG_FILE_NAME,
   loadConfig,
@@ -50,6 +52,51 @@ export {
   type StoredCredential,
 } from "./credentials.ts";
 export { generateDemoSnapshot, type DemoSnapshotOptions } from "./demo.ts";
+export {
+  buildEnrichPlan,
+  createFileEnrichRunStore,
+  DEFAULT_STALE_DAYS,
+  ENRICH_CONFIG_FILE_NAME,
+  enrichRunId,
+  inferIngestObjectType,
+  ingestKeyValue,
+  latestStamps,
+  loadEnrichConfig,
+  matchSourceRecord,
+  parseCsv,
+  parseEnrichConfig,
+  resolveCrmField,
+  selectStaleWork,
+  sourceValueAt,
+  stagedSourceRecords,
+  staleDaysFor,
+  type BuildEnrichPlanOptions,
+  type EnrichAmbiguity,
+  type EnrichConfig,
+  type EnrichCounts,
+  type EnrichFieldConfig,
+  type EnrichMatchConfig,
+  type EnrichMode,
+  type EnrichObjectType,
+  type EnrichPlanResult,
+  type EnrichRun,
+  type EnrichRunStore,
+  type EnrichSourceConfig,
+  type EnrichSourceRecord,
+  type EnrichStamp,
+  type EnrichWorkItem,
+  type MatchOutcome,
+} from "./enrich.ts";
+export {
+  apolloPullKeysForAppend,
+  apolloPullKeysForRefresh,
+  createApolloClient,
+  pullApolloRecords,
+  type ApolloClient,
+  type ApolloClientOptions,
+  type ApolloPullKey,
+  type ApolloPullResult,
+} from "./enrichApollo.ts";
 export {
   diffFindings,
   diffSnapshots,

package/src/marketReport.ts

@@ -438,57 +438,119 @@ export function marketMapToHtml(config: MarketConfig, set: ObservationSet): stri
   const e = escapeHtml;
   const axisHtml = axisSectionsHtml(config, set);
 
-  const matrixRows = model.orderedClaimIds
-    .map((claimId) => {
-      const claim = claimsById.get(claimId);
-      if (!claim) return "";
-      const state = stateByClaim.get(claimId) ?? "vacant";
-      const cells = config.vendors
-        .map((vendor) => {
-          const intensity = model.cell(vendor.id, claimId)?.intensity ?? "unobservable";
-          const anchorClass = vendor.id === anchor ? " anchor-col" : "";
-          return `<td class="cell${anchorClass}"><span class="g g-${intensity}" title="${e(vendor.name)}: ${intensity}"></span></td>`;
-        })
-        .join("");
-      return (
-        `<tr class="front-${state}"><th scope="row"><span class="claim-cap">${e(claim.capability.split(":")[0])}</span>` +
-        `<span class="claim-meta">${e(claim.icp)} · ${e(claim.pricingStructure)}</span></th>${cells}` +
-        `<td class="front"><span class="chip chip-${state}">${state.toUpperCase()}</span></td></tr>`
-      );
-    })
+  const vendorNamesById = new Map(config.vendors.map((vendor) => [vendor.id, vendor.name]));
+  const frontByClaim = new Map(model.fronts.map((front) => [front.claimId, front]));
+
+  const matrixRow = (claimId: string): string => {
+    const claim = claimsById.get(claimId);
+    if (!claim) return "";
+    const state = stateByClaim.get(claimId) ?? "vacant";
+    const cells = config.vendors
+      .map((vendor) => {
+        const intensity = model.cell(vendor.id, claimId)?.intensity ?? "unobservable";
+        const anchorClass = vendor.id === anchor ? " anchor-col" : "";
+        return `<td class="cell${anchorClass}"><span class="g g-${intensity}" title="${e(vendor.name)}: ${intensity}"></span></td>`;
+      })
+      .join("");
+    return (
+      `<tr class="front-${state}"><th scope="row"><span class="claim-cap">${e(claim.capability.split(":")[0])}</span>` +
+      `<span class="claim-meta">${e(claim.icp)} · ${e(claim.pricingStructure)}</span></th>${cells}` +
+      `<td class="front"><span class="chip chip-${state}">${state.toUpperCase()}</span></td></tr>`
+    );
+  };
+
+  const vendorHeads = config.vendors
+    .map(
+      (vendor) =>
+        `<th class="vh${vendor.id === anchor ? " anchor-col" : ""}"><span>${e(vendor.name)}</span></th>`,
+    )
     .join("");
 
-  const openList = model.orderedClaimIds
-    .filter((claimId) => {
-      const state = stateByClaim.get(claimId);
-      return state === "open" || state === "vacant";
-    })
+  // Claims grouped by front state, each group a collapsed <details> whose
+  // summary carries the stats a skimmer needs; the full matrix is one click
+  // away, not a wall the reader must climb to reach the takeaway.
+  const GROUPS: Array<{ states: FrontState[]; title: string; blurb: string }> = [
+    { states: ["open", "vacant"], title: "Open ground", blurb: "no vendor is loud here" },
+    { states: ["contested"], title: "Contested fronts", blurb: "2–3 vendors loud" },
+    { states: ["owned"], title: "Owned fronts", blurb: "exactly one vendor loud" },
+    { states: ["saturated"], title: "Saturated fronts", blurb: "4+ vendors loud" },
+  ];
+  const groupedMatrix = GROUPS.map((group) => {
+    const claimIds = model.orderedClaimIds.filter((claimId) => group.states.includes(stateByClaim.get(claimId) ?? "vacant"));
+    if (claimIds.length === 0) return "";
+    const anchorLoud = anchor
+      ? claimIds.filter((claimId) => model.cell(anchor, claimId)?.intensity === "loud").length
+      : 0;
+    const anchorNote = anchor ? ` · ${vendorNamesById.get(anchor) ?? anchor} loud on ${anchorLoud}` : "";
+    return `<details class="claim-group"><summary><b>${e(group.title)}</b> — ${claimIds.length} claim${claimIds.length === 1 ? "" : "s"} <span class="sum-soft">(${e(group.blurb)}${anchorNote})</span></summary>
+      <table><thead><tr><th></th>${vendorHeads}<th></th></tr></thead><tbody>${claimIds.map(matrixRow).join("")}</tbody></table>
+    </details>`;
+  }).join("");
+
+  // The closing argument: walk from open ground to a reasoned target list.
+  const openFronts = model.orderedClaimIds.filter((claimId) => {
+    const state = stateByClaim.get(claimId);
+    return state === "open" || state === "vacant";
+  });
+  const targetItems = openFronts
     .map((claimId) => {
       const claim = claimsById.get(claimId);
-      return `<li><b>${e(claim?.capability.split(":")[0] ?? claimId)}</b> <span class="why">— no vendor is loud here; ${e(claim?.icp ?? "")} cell</span></li>`;
+      const front = frontByClaim.get(claimId);
+      if (!claim || !front) return "";
+      const quietNames = front.quietVendorIds.map((id) => vendorNamesById.get(id) ?? id);
+      const anchorIntensity = anchor ? model.cell(anchor, claimId)?.intensity ?? "unobservable" : null;
+      const nearest =
+        quietNames.length > 0
+          ? `Closest contenders (quiet): ${quietNames.join(", ")}.`
+          : "Nobody even ships it quietly — vacant ground.";
+      const move =
+        anchorIntensity === "quiet"
+          ? `${e(vendorNamesById.get(anchor as string) ?? "The anchor")} already ships this quietly — a promote-to-loud candidate.`
+          : anchorIntensity === "absent"
+            ? "Unclaimed by the anchor: a first-mover messaging opportunity if the capability is real or buildable."
+            : "";
+      return `<li><b>${e(claim.capability.split(":")[0])}</b> <span class="sum-soft">(${e(claim.icp)} · ${e(claim.pricingStructure)})</span><br>
+        No vendor is loud on this claim. ${e(nearest)} ${move}</li>`;
     })
     .join("");
+  const heldFronts = anchor
+    ? model.fronts.filter((front) => front.state === "owned" && front.loudVendorIds[0] === anchor)
+    : [];
+  const heldLine =
+    heldFronts.length > 0
+      ? `<p><b>Held ground:</b> ${e(vendorNamesById.get(anchor as string) ?? "the anchor")} is the sole loud vendor on ${heldFronts
+          .map((front) => `<i>${e(claimsById.get(front.claimId)?.capability.split(":")[0] ?? front.claimId)}</i>`)
+          .join(", ")} — positions to defend, not abandon.</p>`
+      : "";
+  const crowdLine =
+    counts.saturated > 0
+      ? `<p><b>Crowded ground:</b> ${counts.saturated} claim${counts.saturated === 1 ? " is" : "s are"} saturated (4+ vendors loud) — message budget spent there buys the least differentiation.</p>`
+      : "";
+  const takeaway = `<section>
+  <h2>Where to attack</h2>
+  <p class="lede">${openFronts.length === 0 ? "No open fronts this run — every claim has at least one loud vendor. Watch the drift between runs for windows opening." : `${openFronts.length} claim${openFronts.length === 1 ? "" : "s"} in this category ${openFronts.length === 1 ? "is" : "are"} open: buyers can be reached there without out-shouting anyone.`}</p>
+  <ul class="targets">${targetItems}</ul>
+  ${heldLine}
+  ${crowdLine}
+  <p class="sum-soft">These are messaging fronts, not verdicts — join the map to CRM ground truth (\`market overlay\`) for evidence-backed OCCUPY / PROMOTE / URGENT / RETREAT directives with win-rate stats.</p>
+</section>`;
 
-  const appendix = model.orderedClaimIds
-    .flatMap((claimId) =>
-      config.vendors.flatMap((vendor) => {
+  // Evidence grouped by vendor, collapsed: receipts on demand, not a scroll wall.
+  const appendixGroups = config.vendors
+    .map((vendor) => {
+      const items = model.orderedClaimIds.flatMap((claimId) => {
         const obs = model.cell(vendor.id, claimId);
         if (!obs || obs.evidence.length === 0) return [];
         return obs.evidence.map(
           (evidence) =>
-            `<div class="ev"><span class="ev-head">${e(vendor.name)} · ${e(claimId)} · ${obs.intensity.toUpperCase()} (${obs.confidence})</span>` +
+            `<div class="ev"><span class="ev-head">${e(claimId)} · ${obs.intensity.toUpperCase()} (${obs.confidence})</span>` +
             `<blockquote>“${e(evidence.text)}”</blockquote>` +
             `<span class="ev-src">${e(String(evidence.metadata?.url ?? ""))} · capture ${e(String(evidence.metadata?.captureHash ?? "").slice(0, 12))}</span></div>`,
         );
-      }),
-    )
-    .join("");
-
-  const vendorHeads = config.vendors
-    .map(
-      (vendor) =>
-        `<th class="vh${vendor.id === anchor ? " anchor-col" : ""}"><span>${e(vendor.name)}</span></th>`,
-    )
+      });
+      if (items.length === 0) return "";
+      return `<details class="ev-group"><summary><b>${e(vendor.name)}</b> <span class="sum-soft">— ${items.length} quoted span${items.length === 1 ? "" : "s"}</span></summary>${items.join("")}</details>`;
+    })
     .join("");
 
   return `<!doctype html>
@@ -506,14 +568,16 @@ h1 { font-size:27px; font-weight:600; line-height:1.2; }
 .meta { font-size:11px; color:var(--soft); display:flex; gap:18px; flex-wrap:wrap; margin-top:8px; }
 section { margin-top:44px; }
 h2 { font-size:17px; font-weight:600; border-bottom:1px solid var(--line); padding-bottom:7px; margin-bottom:4px; }
-.fronts { display:grid; grid-template-columns:repeat(4,1fr); gap:1px; background:var(--line); border:1px solid var(--line); margin-top:16px; }
-.fcard { background:#fff; padding:14px 16px 12px; }
-.fcard b { display:block; font-size:30px; font-weight:600; line-height:1.1; }
-.fcard span { font-size:11px; color:var(--soft); }
-.fcard.open b { color:var(--accent); }
-.openlist { margin-top:14px; font-size:14.5px; line-height:1.55; }
-.openlist li { margin:3px 0 3px 20px; }
-.openlist .why { color:var(--soft); font-size:13px; }
+details.claim-group, details.ev-group { border:1px solid var(--line); border-radius:3px; margin-top:10px; }
+details.claim-group summary, details.ev-group summary { cursor:pointer; padding:10px 14px; font-size:14px; list-style-position:inside; }
+details.claim-group summary:hover, details.ev-group summary:hover { background:var(--faint); }
+details.claim-group[open] summary, details.ev-group[open] summary { border-bottom:1px solid var(--line); }
+details.claim-group table { margin:4px 12px 12px; width:calc(100% - 24px); }
+details.ev-group .ev { margin:0 14px; }
+.sum-soft { color:var(--soft); font-size:12px; }
+.lede { font-size:16px; margin-top:12px; }
+.targets { margin-top:12px; font-size:14.5px; line-height:1.6; }
+.targets li { margin:10px 0 10px 20px; }
 .key { display:flex; gap:20px; flex-wrap:wrap; margin:14px 0 8px; font-size:10.5px; color:var(--soft); }
 .lg { display:inline-flex; align-items:center; gap:6px; }
 table { border-collapse:collapse; width:100%; margin-top:6px; }
@@ -574,34 +638,24 @@ footer { margin-top:60px; border-top:1px solid var(--ink); padding-top:12px; fon
     <span>extractor: ${e(set.extractor)}</span>
   </div>
 </header>
+${axisHtml.strategicMap}
 <section>
-  <h2>Front summary</h2>
-  <div class="fronts">
-    <div class="fcard open"><b>${counts.open + counts.vacant}</b><span>Open / vacant</span></div>
-    <div class="fcard"><b>${counts.contested}</b><span>Contested</span></div>
-    <div class="fcard"><b>${counts.owned}</b><span>Owned</span></div>
-    <div class="fcard"><b>${counts.saturated}</b><span>Saturated</span></div>
-  </div>
-  <ul class="openlist">${openList}</ul>
-</section>
-<section>
-  <h2>Claim × vendor intensity matrix</h2>
+  <h2>Market Claims</h2>
   <div class="key">
     <span class="lg"><i class="g g-loud"></i>LOUD — hero-level claim</span>
     <span class="lg"><i class="g g-quiet"></i>QUIET — shipped, buried</span>
     <span class="lg"><i class="g g-absent"></i>ABSENT</span>
     <span class="lg"><i class="g g-unobservable"></i>UNOBSERVABLE — capture failed</span>
   </div>
-  <table>
-    <thead><tr><th></th>${vendorHeads}<th></th></tr></thead>
-    <tbody>${matrixRows}</tbody>
-  </table>
+  ${groupedMatrix}
 </section>
-${axisHtml.strategicMap}
+${takeaway}
 <section>
   <h2>Evidence appendix</h2>
-  ${appendix}
+  <p class="sum-soft">Every loud/quiet reading is grounded in a verbatim span from a stored page capture; expand a vendor for its receipts.</p>
+  ${appendixGroups}
 </section>
+<script>window.addEventListener("beforeprint",function(){document.querySelectorAll("details").forEach(function(d){d.open=true;});});</script>
 <footer>
   <span>Generated by fullstackgtm market · deterministic render of ${e(set.runLabel)}</span>
   <span>Front rule v1: 0 loud=open · 1=owned · 2–3=contested · ≥4=saturated</span>

package/src/reassign.ts

@@ -0,0 +1,117 @@
+/**
+ * The ownership-handoff playbook: `reassign` compiles one bulk-update-style
+ * dry-run plan PER object type (accounts, contacts, deals by default) that
+ * moves every record owned by --from to --to. It NEVER writes — each plan
+ * flows through the same plans-approve → apply gate, and because every plan
+ * carries its full filter, eligibility (extra --where scoping AND the
+ * --except-deal-stage exclusion) is re-verified per record against a FRESH
+ * snapshot at apply time, with mid-apply rechecks. A record that drifts into
+ * the exception set mid-run surfaces as a conflict, not a bad write.
+ *
+ * --except-deal-stage <stage> excludes in-flight business end to end:
+ *   - deal plans drop deals in that stage (stage!=<stage>), and
+ *   - ALL plans drop records whose account has an OPEN deal in that stage
+ *     (accounts: openDealStages!~<stage>; deals/contacts:
+ *     account.openDealStages!~<stage>).
+ *
+ * Deal plans cover OPEN deals only unless includeClosedDeals is set: closed
+ * deals keep their historical owner in a handoff.
+ *
+ * Extra --where clauses are account-scoped where needed: a clause on a field
+ * that only exists on accounts (e.g. domain~.de) is lifted to the relational
+ * pseudo-field (account.domain~.de) for contact and deal plans, so one
+ * invocation scopes all three object types consistently.
+ */
+import { buildBulkUpdatePlan, isFilterableField, parseWhere } from "./bulkUpdate.ts";
+import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+
+export type ReassignObjectType = "account" | "contact" | "deal";
+
+export type ReassignOptions = {
+  /** the owner whose records are being handed off */
+  fromOwnerId: string;
+  /** the receiving owner — must be a known user in the snapshot */
+  toOwnerId: string;
+  /** which object types to compile plans for (default all three) */
+  objects?: ReassignObjectType[];
+  /** extra --where scoping, AND-ed into every plan (account fields lifted) */
+  where?: string[];
+  /** exclude records tied to an open deal in this stage (see module doc) */
+  exceptDealStage?: string;
+  /** also reassign closed deals (default false: history keeps its owner) */
+  includeClosedDeals?: boolean;
+  reason?: string;
+  maxOperations?: number;
+};
+
+const ALL_OBJECTS: ReassignObjectType[] = ["account", "contact", "deal"];
+
+/**
+ * Scope an extra --where clause to one object type: pass through when the
+ * field is valid there, lift account-only fields to account.<field> for
+ * contacts and deals. Unknown fields fall through to buildBulkUpdatePlan's
+ * strict validation, which throws with the valid-field list.
+ */
+function scopeWhere(objectType: ReassignObjectType, raw: string): string {
+  const clause = parseWhere(raw);
+  if (isFilterableField(objectType, clause.field)) return raw;
+  if (objectType !== "account" && isFilterableField(objectType, `account.${clause.field}`)) {
+    return `account.${raw}`;
+  }
+  return raw;
+}
+
+export function buildReassignPlans(
+  snapshot: CanonicalGtmSnapshot,
+  options: ReassignOptions,
+): PatchPlan[] {
+  if (!options.fromOwnerId || !options.toOwnerId) {
+    throw new Error("reassign requires both --from <ownerId> and --to <ownerId>.");
+  }
+  if (options.fromOwnerId === options.toOwnerId) {
+    throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+  }
+  // The receiving owner must exist: a typo'd --to would otherwise write an
+  // invalid owner onto every matched record.
+  if (!snapshot.users.some((user) => user.id === options.toOwnerId)) {
+    throw new Error(
+      `reassign --to ${options.toOwnerId} is not a known user in the snapshot. Known users: ${snapshot.users
+        .map((user) => `${user.id} (${user.name})`)
+        .join(", ") || "none"}.`,
+    );
+  }
+  const objects = options.objects ?? ALL_OBJECTS;
+  for (const objectType of objects) {
+    if (!ALL_OBJECTS.includes(objectType)) {
+      throw new Error(`reassign --objects supports account, contact, deal — got "${objectType}".`);
+    }
+  }
+
+  return objects.map((objectType) => {
+    const where = [`ownerId=${options.fromOwnerId}`];
+    if (objectType === "deal" && !options.includeClosedDeals) {
+      where.push("isClosed=false"); // closed deals keep their historical owner
+    }
+    for (const extra of options.where ?? []) {
+      where.push(scopeWhere(objectType, extra));
+    }
+    if (options.exceptDealStage) {
+      const stage = options.exceptDealStage;
+      if (objectType === "deal") where.push(`stage!=${stage}`);
+      where.push(
+        objectType === "account"
+          ? `openDealStages!~${stage}`
+          : `account.openDealStages!~${stage}`,
+      );
+    }
+    return buildBulkUpdatePlan(snapshot, {
+      objectType,
+      where,
+      set: { ownerId: options.toOwnerId },
+      reason:
+        options.reason ??
+        `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`,
+      maxOperations: options.maxOperations,
+    });
+  });
+}