fullstackgtm 0.34.0 → 0.38.0

package/docs/architecture.md

@@ -72,7 +72,17 @@ provider  ──fetchSnapshot()──►  CanonicalGtmSnapshot
 - `market*.ts` (`market.ts`, `marketClassify.ts`, `marketAxes.ts`,
   `marketOverlay.ts`, `marketScale.ts`, `marketReport.ts`) — the competitive
   market-map layer; classifications are verbatim-verified against captures.
-- `enrich.ts` + `enrichApollo.ts` — third-party data enrichment (fill-blanks).
+- `enrich.ts` + `enrichApollo.ts` — third-party data enrichment (fill-blanks),
+  plus `buildAcquirePlan` / `builtinAcquirePreset` for net-new lead generation.
+- `icp.ts` — the Ideal Customer Profile artifact: per-provider discovery-filter
+  translation, prospect fit scoring, and the agent-driven interview spec.
+- `acquireMeter.ts` — per-profile windowed budget (records + spend) for acquire.
+- `acquireSeen.ts` — cross-run "seen" cache so re-runs don't re-pay for dupes.
+- `assign.ts` — `AssignmentPolicy` (fixed / round-robin / territory /
+  account-owner): the pure owner-routing rule `buildAcquirePlan` stamps onto new
+  leads (never born ownerless) and `reassign --assign-unowned` reuses to backfill.
+- `connectors/prospectSources.ts` — API prospect sources (Explorium discovery,
+  pipe0 work-email waterfall, pipe0/Crustdata search) + the pre-email dedup keys.
 
 **Surfaces & infra**
 - `cli.ts` — one async function per command, flat dispatch in `runCli`;

package/docs/dx-punch-list.md

@@ -0,0 +1,87 @@
+# DX / adoption punch list
+
+Audit date: 2026-06-19. Method: ran the CLI as a new adopter would (bare
+invoke → `doctor` → `audit --demo` → per-command `--help`) and measured the
+friction, rather than reading the source. Companion to the security/strategic
+findings that drove the 0.25.1–0.28.0 hardening releases — same format, same
+intent: a tracked list that drives a release.
+
+## Framing
+
+The **agent path** (SKILL.md verb map, MCP tools, `--json` everywhere,
+gate-shaped exit codes 0/1/2) is cohesive and adopts cleanly. The **human
+path** is the weak side — and the human is a primary user (the consultant-CLI,
+dogfood-on-client-work direction). Every fix below either *deepens an existing
+verb* or *connects two existing verbs*; none adds a new top-level noun. The
+adoption work **is** the "deeper not broader" work.
+
+`doctor` (ends with "Next step") and `fix` (chains audit→suggest→approve→apply)
+already do the right thing. Cohesion here = make every verb behave like
+`doctor` and `fix` already do.
+
+## Findings (evidence-backed)
+
+| # | Finding | Evidence | Impact |
+| --- | --- | --- | --- |
+| F1 | **Front door is a firehose** | bare invoke = 194 lines; 22 verbs / 87 distinct flags; `cli.ts` is 3,615 lines | New user can't find the ~6 things they actually do |
+| F2 | **Credential-free entry point dead-ends** | `audit --demo` (the README's "try it first") dumps **1,467 lines** to stdout and ends on a blank line — no "next step," unlike `doctor` | The single most-run first command strands you |
+| F3 | **No per-command help** | `dedupe --help`, `audit --help` fall through to the same 194-line global wall | A stuck user gets the firehose, not the answer |
+| F4 | **No altitude control on reads** | `audit` has only `--json` / `--out` / `--format`; no `--summary` / `--top` / `--quiet`. Human mode *is* the 1,467-line dump | Default human output is unreadable yet not machine-parseable |
+| F5 | **Tone undercuts positioning** | `audit --demo` footer: "This prototype is dry-run only" | Reads as toy vs. the beta/production-safety-invariant framing |
+| F6 | **No guided mode** | `readline` is used only for the login secret prompt | Every workflow is hand-assembled from flags; nothing scaffolds the loop |
+
+## Fix sequence (highest leverage first)
+
+### 1. Progressive-disclosure help — IN PROGRESS
+Fixes **F1, F3**. The full `usage()` becomes the explicit full reference
+(`fullstackgtm help --full`). Add:
+- `shortUsage()` — a ~30-line map of the verbs grouped by lifecycle phase
+  (Setup · Detect · Prevent · Remediate · Calls · Govern · Market · Schedule),
+  one line each, ending with `<command> --help` and `help --full` pointers.
+  Becomes the default for bare invoke and `--help`.
+- `commandHelp(command)` — focused per-verb help (summary, synopsis, where it
+  sits in the loop, key options, see-also). `<verb> --help` zooms in instead
+  of dumping the surface. `call`/`market`/`enrich`/`bulk-update`/`schedule`
+  keep their existing bespoke help.
+- `help [command] [--full]` command.
+
+### 2. Every verb hands you the next step — DONE (audit keystone)
+Fixes **F2**. `auditNextStep()` gives `audit` context-aware forward guidance on
+stderr (stdout stays clean for pipes/`--out`; suppressed under `--json`):
+- **demo/sample** → "Client-ready writeup: `report --demo`" + "Run on your CRM:
+  `login hubspot` → `audit --provider hubspot --save`"
+- **live + `--save`** → the governed spine: `suggest` → `plans approve
+  --values-from` → `apply`, with the real plan id
+- **0 findings** → "clean — gate new records with `resolve`, schedule a check"
+
+The lifecycle spine made *experiential* — each command knows its phase and
+points forward (`doctor`/`fix` were the templates). `audit` is the keystone
+(the documented dead-end); the helper pattern now generalizes to the other read
+verbs (`report`, `resolve`, `dedupe` previews) in a follow-up.
+
+### 3. Altitude control on the firehose — DONE
+Fixes **F4**. `patchPlanToMarkdown(plan, { summary })` gains a summary view
+(header + Findings-by-Rule table + operation count + pointers to `--full` and
+`report`). `audit` defaults to it — **1,467 → 24 lines** on the demo — with
+`--full` to opt back into the per-operation dump. The default stays *full* for
+every other caller (bulk-update, fix, dedupe, plans show, MCP): write-preview
+verbs keep full operation detail because you approve specific ops there. The
+principled split — audit = "what's wrong" (summary → `report`); write verbs =
+"exactly what I'll change" (full) — is the real win.
+
+### 4. Tone pass — DONE
+Fixes **F5**. The "This prototype is dry-run only" footer is replaced
+everywhere with safety-invariant framing matching README/SKILL: "Dry-run plan —
+read-only. No provider write happens until you approve specific operations and
+run `apply`; placeholder values are refused without an explicit override. These
+safety invariants are not beta." No "prototype" string remains in user output.
+
+## Deferred (bigger bets, gated on 1–4 landing)
+- **Engagement workspace**: per-client `.fullstackgtm/` state that accumulates
+  snapshots, plans, evidence, and a health-over-time score — turns episodic
+  audits into a continuously-operated system.
+- **Journey commands**: 2–3 opinionated composites (onboard-a-client,
+  health-rollup) sequencing existing verbs into revops jobs.
+
+There is no point building the engagement workspace while the front door dumps
+1,467 lines. Land the DX fixes first.

package/docs/linkedin-connector-spec.md

@@ -0,0 +1,87 @@
+# `linkedin` connector — spec (Phase 1)
+
+Status: scoped 2026-06-20. Decisions locked: **first slice = Phase 1 discovery,
+dry-run; default provider = HeyReach.** Rationale + the full white-label
+investigation that motivated owning this: see the LinkedIn connector research.
+
+## Why this shape
+
+The research verdict (≈85%): Gojiberry runs its **own** LinkedIn session-automation
+stack — it is **not** white-labeling HeyReach/Unipile, so there is no upstream to
+go "direct" to. But Gojiberry proves a small team can build the architecture, and
+the *execution* layer is rentable. So FSGTM's play is: **rent execution
+(HeyReach), own the targeting + scoring + plan/apply governance** — "governed
+LinkedIn outbound," which nobody else has.
+
+This does **not** rebuild anything. The in-flight `enrich acquire` pipeline
+already is the spine:
+
+```
+Icp → discovery source (Explorium/pipe0/Clay) → scoreProspectAgainstIcp
+   → partitionFreshProspects (dedup vs CRM + acquireSeen) → create_record op
+   → acquireMeter budget cap → approve → apply
+```
+
+LinkedIn is just a **new discovery source** on that spine.
+
+## Phase 1 deliverable: `enrich acquire --source linkedin` (dry-run)
+
+ICP → LinkedIn people-search via HeyReach → `Prospect[]` → ICP-scored → deduped →
+**dry-run `create_record` plan** (no `--save` ⇒ nothing written, zero send/ToS
+exposure). Net-new code is small; scoring/dedup/metering/apply are reused.
+
+### Components
+- **`src/connectors/linkedin.ts`** (mirrors `prospectSources.ts`):
+  - `icpToLinkedInFilters(icp)` — `Icp` → LinkedIn/Sales-Nav search params (mirror
+    of `icpToExploriumFilters` / `icpToCrustdataFilters` in `icp.ts`).
+  - `discoverProspects(provider, filters, max)` — search mode for Phase 1; returns
+    the existing `Prospect` type so everything downstream is free.
+- **`LinkedInProvider` interface** (injectable, like `CrontabIo`): default
+  **HeyReach** adapter (`searchLeads` / lead-list pull), plus a **`FakeLinkedInProvider`**
+  for tests so the whole pipeline runs with no key and no network.
+- **`builtinAcquirePreset('linkedin')`** — zero-config source preset (match-key
+  email/linkedinUrl; cost-per-record for the meter).
+- **Wiring**: register `linkedin` in the `enrich acquire` source switch; add to
+  the source allowlist + help; `login heyreach` (or `HEYREACH_API_KEY`) for the key.
+
+### Reused as-is (no change)
+`scoreProspectAgainstIcp`, `partitionFreshProspects`, `acquireSeen`,
+`acquireMeter` (records/day+month, cost/record), the `create_record` op + apply
+path, the dry-run→approve→apply gate.
+
+## Out of scope for Phase 1 (explicit)
+- **No sending.** `linkedin_connect` / `linkedin_message` operations, the
+  per-sender safety meter, and HeyReach webhook ingestion are **Phase 2**.
+- Engagement-signal capture (Gojiberry-style intent from who-engaged-our-posts)
+  is a Phase 1.5 add to `discoverProspects` once search mode is trusted.
+- Not our own automation engine; not the official LinkedIn API; not multi-channel.
+
+## Provider: HeyReach
+Behind `LinkedInProvider` so we are not locked in (Unipile = documented
+alternative: cheaper raw search/profile, multi-channel). HeyReach chosen for the
+full Campaign API + webhooks + sender rotation + built-in per-account caps (the
+Phase 2 ban-safety primitives we will want). ToS/ban risk sits on the connected
+LinkedIn account — same posture as Gojiberry today.
+
+## Build sequencing (IMPORTANT)
+The acquire spine (`icp.ts`, `prospectSources.ts`, `acquireMeter.ts`,
+`acquireSeen.ts`) is **uncommitted, actively-edited working-tree code** (not on
+main). Building the acquire-source wiring on top of it is expansion on an
+unstable base. Therefore:
+
+1. **Buildable now (self-contained, no dep on the uncommitted acquire internals):**
+   `LinkedInProvider` interface + HeyReach adapter (coded to HeyReach's documented
+   API) + `FakeLinkedInProvider` + `icpToLinkedInFilters` + unit tests against the
+   fake.
+2. **After the acquire workstream commits/lands:** wire `enrich acquire --source
+   linkedin` end-to-end and add the dry-run integration test.
+3. **Live validation** needs a HeyReach trial API key (Ryan provides) — the fake
+   covers everything up to the real network call.
+
+## Phase 2 (future, recorded for continuity)
+Governed outbound: `linkedin_connect`/`linkedin_message` as `PatchOperation`s
+(objectId = contact, afterValue = body, approvalRequired, `groupId` = sequence
+all-or-nothing, `preconditions` = not-already-connected); `applyOperation`
+dispatches `linkedin_*` to the provider; per-sender-account daily caps via the
+`acquireMeter` pattern (ban-safety encoded as governance); HeyReach webhooks →
+CRM activity + intent signal. This is the differentiated surface.

package/llms.txt

@@ -76,7 +76,10 @@ identity key — merge with `dedupe` instead. `dedupe <object> --key
 deterministic survivor (`--keep richest|oldest`); merges are irreversible and
 stay low-confidence-capped at approval. `reassign --from <owner> --to
 <owner>` = ownership handoff plans per object type; `--except-deal-stage`
-also excludes records whose account has an open deal in that stage. `fix
+also excludes records whose account has an open deal in that stage;
+`reassign --assign-unowned --to <id>` instead claims every ownerless record
+(`ownerId:empty`) for an owner — the backfill twin of acquire's create-time
+assignment. `fix
 --rule <id>` = audit one rule → suggest → approve at the confidence bar →
 apply only with `--yes`. All four produce plans; none writes outside
 approve → apply.
@@ -95,6 +98,24 @@ where the source value changed (beforeValue = current CRM value → apply-time
 CAS). Conflict policy MVP is `never`; `system-only`/`always` are phase 2 and
 refused explicitly. Run store (checkpoint + staleness ledger + `status`) is
 profile-scoped under `<home>/enrich/runs`. No cron — scheduling is horizontal.
+`acquire` is the one enrich verb that creates net-new records instead of
+filling blanks: it discovers ICP-targeted people, resolves work email, and
+proposes governed `create_record` ops through the same dry-run → approve →
+apply gate — resolve-first dedupe re-checks the key at apply time so it never
+double-creates. A per-profile windowed meter (`acquireMeter.ts`) caps both
+record count and provider spend (per-day + per-month, whichever binds first);
+sources come from staged ingest lists. Acquired leads are never born ownerless:
+an `acquire.assign` policy (`fixed`/`round-robin`/`territory`/`account-owner`,
+or `--assign-owner <id>`) stamps an owner into every `create_record`, gated by
+the snapshot's active owners (unknown/inactive owner → unassigned, never a bad
+owner); with multiple owners and no policy it warns and leaves leads unassigned.
+Discovery sources are presets behind `--source`: `explorium`/`pipe0` (ICP-driven
+people search) and `linkedin` (Phase 1, discovery + dry-run) which reads a
+pre-built HeyReach lead list (`--list <id>` or `acquire.discovery.linkedin.listId`,
+match key = LinkedIn URL, $0/record, `login heyreach`/`HEYREACH_API_KEY`) via the
+injectable `LinkedInProvider` (default HeyReach; `FakeLinkedInProvider` for tests).
+LinkedIn is read-only — Phase 1 has no `linkedin_connect`/`linkedin_message` ops
+and no webhook ingestion (Phase 2). Never auto-writes.
 
 ## Key invariants (schedule)
 
@@ -115,6 +136,22 @@ artifacts: plan ids / enrich run labels, trigger cron|manual) land under
 firings (visibility only — local cron has no catch-up). Providers beyond
 `local` are not yet implemented (future: codegen scaffolds, same contract).
 
+## Key invariants (engagement workspace / health)
+
+`fullstackgtm health` rolls up a per-profile CRM-health timeline that accrues
+from the verb teams already run: every `audit --save` stamps a deterministic
+0–100 hygiene score plus a snapshot onto the active profile. The score is
+`100 / (1 + severity-weighted findings per record)` (info ×1, warning ×3,
+critical ×10) — no LLM, so it is byte-stable in CI and comparable run-over-run;
+0 findings ⇒ 100, and the same findings over fewer clean records score lower.
+State is profile-scoped and owner-only (0600) under the same secured home as
+plans: `health.jsonl` (append-only, one entry per saved audit) and
+`snapshots/<planId>.json`. `health` is READ-ONLY — it only reads the timeline,
+never re-audits or writes; `--json` emits the rollup (current score, delta since
+the last audit, dated trend, per-rule deltas). Scope per client with
+`--profile <name>`; an empty timeline returns a pointer, never an error.
+Library: `computeHealth` / `summarizeHealth` / `healthToMarkdown`.
+
 ## Key invariants
 
 - Reads are safe by default; nothing is written without explicit `--approve`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.34.0",
+  "version": "0.38.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 LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",

package/skills/fullstackgtm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fullstackgtm
-description: Govern CRM/GTM data operations through the fullstackgtm CLI — read-only hygiene audits, reviewable dry-run patch plans, deterministic value suggestions, and approval-gated write-back to HubSpot and Salesforce. Use when asked to audit, clean, dedupe, enrich, bulk-update, reassign, or write to a CRM; to gate record creation against duplicates; to parse, score, or link sales call transcripts; to map a competitive category; or to schedule any of the above. Never write to a CRM directly when this skill is available.
+description: Govern CRM/GTM data operations through the fullstackgtm CLI — read-only hygiene audits, reviewable dry-run patch plans, deterministic value suggestions, and approval-gated write-back to HubSpot and Salesforce. Use when asked to audit, clean, dedupe, enrich, bulk-update, reassign, or write to a CRM; to gate record creation against duplicates; to parse, score, or link sales call transcripts; to map a competitive category; to report a CRM's health and trend over time; or to schedule any of the above. Never write to a CRM directly when this skill is available.
 ---
 
 # fullstackgtm — plan/apply for your GTM stack
@@ -58,13 +58,15 @@ credentials AND stored plans per client org.
 | `resolve <contact\|account\|deal>` | Create gate: exit 0 = safe to create, 2 = exists/ambiguous — never blind-create |
 | `dedupe <object> --key <domain\|email\|name>` | One merge op per duplicate group, deterministic survivor; merges are irreversible |
 | `bulk-update <object> --where … --set\|--archive\|--create-task` | Filtered dry-run plan; filter re-verified per record at apply time |
-| `reassign --from <owner> --to <owner>` | Ownership handoff plans per object type |
+| `reassign --from <owner> --to <owner>` | Ownership handoff plans per object type; `--assign-unowned --to <id>` backfills every ownerless record |
 | `fix --rule <id>` | audit one rule → suggest → approve at the confidence bar → apply only with `--yes` |
 | `call parse\|score\|link\|plan` | Transcripts → evidence-quoted insights, rubric scorecards, deal linking, governed next-step writes |
 | `enrich append\|refresh\|ingest\|status` | Governed enrichment (Apollo pull / Clay ingest), fill-blanks-only plans |
+| `enrich acquire [--source explorium\|pipe0\|linkedin]` | Net-new ICP-targeted lead gen: resolve-first deduped `create_record` plans, capped by a per-profile windowed meter (records + spend); owner-stamped via `acquire.assign`/`--assign-owner` (never born ownerless); `--source linkedin --list <id>` reads a HeyReach lead list (Phase 1 discovery, read-only — never sends); never auto-writes |
 | `market init\|capture\|classify\|worksheet\|observe\|fronts\|axes\|overlay\|scale\|report\|refresh` | Competitive category map; evidence quotes verified verbatim against stored captures |
 | `schedule add\|list\|remove\|enable\|disable\|run\|install\|uninstall\|status` | Horizontal cron; read/plan-side allowlist only — scheduling NEVER auto-approves |
 | `report` | Client-ready audit deliverable (markdown or self-contained HTML) |
+| `health [--json]` | Per-profile CRM health timeline: deterministic 0–100 score, trend, per-rule deltas — accrues from `audit --save`, read-only |
 | `plans list\|show\|approve\|reject` / `snapshot` / `rules` / `doctor` | Plan lifecycle, raw snapshots, rule registry, machine state |
 
 All write-shaped verbs produce plans; none writes outside approve → apply.
@@ -84,6 +86,6 @@ Tools over stdio: `fullstackgtm_audit` (read-only), `fullstackgtm_rules`,
 
 ## Going deeper
 
-- [llms.txt](https://github.com/fullstackgtm/core/blob/main/llms.txt) — the full invariant map per layer (calls, market, write verbs, enrich, schedule)
+- [llms.txt](https://github.com/fullstackgtm/core/blob/main/llms.txt) — the full invariant map per layer (calls, market, write verbs, enrich, schedule, engagement/health)
 - [INSTALL_FOR_AGENTS.md](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md) — deterministic install-and-verify with expected outputs
 - [docs/api.md](https://github.com/fullstackgtm/core/blob/main/docs/api.md) — semver-covered surfaces: canonical model, rule interface, plan/apply contract, connectors, config, CLI, MCP

package/src/acquireLinkedIn.ts

@@ -0,0 +1,83 @@
+/**
+ * LinkedIn → acquire bridge (Phase 1, step 2).
+ *
+ * Connects the provider-agnostic LinkedIn discovery layer (connectors/linkedin.ts)
+ * to the `enrich acquire` spine: pull prospects from a LinkedIn source, map them
+ * to the canonical `Prospect`, and hand them to the existing ICP-score → dedup →
+ * create_record → meter → dry-run/apply pipeline unchanged.
+ *
+ * Kept out of cli.ts on purpose: the only remaining wiring is a ~3-line
+ * discovery branch in `acquireFromApi` (call `createLinkedInProvider` +
+ * `discoverLinkedInProspects`), a `builtinAcquirePreset('linkedin')` entry, the
+ * source allowlist/help, and a `login heyreach` credential. That lands once
+ * cli.ts is clean of other in-flight work — see docs/linkedin-connector-spec.md.
+ *
+ * HeyReach reads a pre-populated lead LIST (not an ICP-driven search), and the
+ * natural identity key is the LinkedIn profile URL — so acquire's matchKey is
+ * `linkedin`, which means the spine skips pipe0 email resolution automatically.
+ */
+
+import {
+  createHeyReachProvider,
+  type HeyReachProviderOptions,
+  type LinkedInProspect,
+  type LinkedInProvider,
+} from "./connectors/linkedin.ts";
+import type { Prospect } from "./connectors/prospectSources.ts";
+
+/** Map a normalized LinkedIn prospect into the canonical acquire `Prospect`. */
+export function linkedInProspectToProspect(lp: LinkedInProspect): Prospect {
+  return {
+    firstName: lp.firstName || undefined,
+    lastName: lp.lastName || undefined,
+    fullName: lp.fullName,
+    // Title drives ICP scoring; fall back to the headline when no title is set.
+    jobTitle: lp.jobTitle ?? lp.headline,
+    companyName: lp.company,
+    linkedin: lp.profileUrl || undefined,
+    email: lp.email,
+    // The profile URL is LinkedIn's stable native id — use it for traceability.
+    sourceId: lp.profileUrl || undefined,
+  };
+}
+
+export type DiscoverLinkedInOptions = {
+  /** Which source (HeyReach lead-list id) to read; provider may have a default. */
+  sourceId?: string;
+  /** Hard cap on prospects pulled. */
+  max?: number;
+};
+
+/**
+ * Discovery branch for `acquireFromApi`: read prospects from a LinkedIn source
+ * and return them as canonical `Prospect`s. Read-only — never sends. The
+ * provider is injected so this is fully testable against the fake (no key).
+ */
+export async function discoverLinkedInProspects(
+  provider: LinkedInProvider,
+  options: DiscoverLinkedInOptions = {},
+): Promise<Prospect[]> {
+  const raw = await provider.fetchProspects({ sourceId: options.sourceId, max: options.max });
+  return raw.map(linkedInProspectToProspect);
+}
+
+export type CreateLinkedInProviderOptions = Omit<HeyReachProviderOptions, "apiKey">;
+
+/**
+ * Build the execution provider for a LinkedIn acquire source. HeyReach is the
+ * default; `unipile` is the planned alternative (same interface). Called by the
+ * cli acquire branch with the stored/env API key.
+ */
+export function createLinkedInProvider(
+  source: string,
+  apiKey: string,
+  options: CreateLinkedInProviderOptions = {},
+): LinkedInProvider {
+  switch (source) {
+    case "linkedin":
+    case "heyreach":
+      return createHeyReachProvider({ apiKey, ...options });
+    default:
+      throw new Error(`Unknown LinkedIn execution provider "${source}" (supported: heyreach).`);
+  }
+}

package/src/acquireMeter.ts

@@ -0,0 +1,186 @@
+/**
+ * The acquire meter — a persistent, windowed budget for net-new lead creation.
+ *
+ * `enrich acquire` proposes `create_record` operations; `apply` writes them.
+ * Both gate on this meter so a profile can never create more leads — or spend
+ * more on enrichment — than its declared budget, per day AND per month
+ * (whichever limit is hit first). The meter is the volume control; a human
+ * still approves the plan (the CLI never auto-writes). State is per-profile,
+ * stored under the credential home so one client's budget never bleeds into
+ * another's.
+ *
+ * Pure where it counts: window math and `remaining()` take an explicit `now`
+ * and operate on a passed-in state, so they are deterministic and testable.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { credentialsDir } from "./credentials.ts";
+
+/** Budget declared in enrich.config.json under `acquire.budget`. */
+export type AcquireBudget = {
+  records?: { perDay?: number; perMonth?: number };
+  spend?: { perDay?: number; perMonth?: number; currency?: string };
+};
+
+export type AcquireMeterState = {
+  /** UTC day bucket, YYYY-MM-DD. */
+  day: string;
+  /** UTC month bucket, YYYY-MM. */
+  month: string;
+  records: { day: number; month: number };
+  spendUsd: { day: number; month: number };
+};
+
+export type AcquireRemaining = {
+  /** Remaining headroom per window; null = no budget set for that dimension. */
+  records: { day: number | null; month: number | null };
+  spendUsd: { day: number | null; month: number | null };
+  /**
+   * The single number that matters: how many MORE records may be created right
+   * now, given every budget dimension and the per-record cost. null = unlimited
+   * (no budget constrains creation). 0 = budget exhausted.
+   */
+  maxRecords: number | null;
+};
+
+export function dayKey(now: Date): string {
+  return now.toISOString().slice(0, 10);
+}
+
+export function monthKey(now: Date): string {
+  return now.toISOString().slice(0, 7);
+}
+
+export function acquireMeterPath(baseDir?: string): string {
+  return join(baseDir ?? credentialsDir(), "acquire", "meter.json");
+}
+
+function emptyState(now: Date): AcquireMeterState {
+  return {
+    day: dayKey(now),
+    month: monthKey(now),
+    records: { day: 0, month: 0 },
+    spendUsd: { day: 0, month: 0 },
+  };
+}
+
+/**
+ * Roll the window counters forward: a new UTC day zeroes the day buckets, a
+ * new UTC month zeroes the month buckets. Returns a fresh object; never
+ * mutates the input.
+ */
+export function rollWindows(state: AcquireMeterState, now: Date): AcquireMeterState {
+  const today = dayKey(now);
+  const thisMonth = monthKey(now);
+  return {
+    day: today,
+    month: thisMonth,
+    records: {
+      day: state.day === today ? state.records.day : 0,
+      month: state.month === thisMonth ? state.records.month : 0,
+    },
+    spendUsd: {
+      day: state.day === today ? state.spendUsd.day : 0,
+      month: state.month === thisMonth ? state.spendUsd.month : 0,
+    },
+  };
+}
+
+/** Load the meter from disk, rolling stale windows forward. Missing = empty. */
+export function loadMeter(now: Date, baseDir?: string): AcquireMeterState {
+  let raw: string;
+  try {
+    raw = readFileSync(acquireMeterPath(baseDir), "utf8");
+  } catch {
+    return emptyState(now);
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<AcquireMeterState>;
+    const state: AcquireMeterState = {
+      day: typeof parsed.day === "string" ? parsed.day : dayKey(now),
+      month: typeof parsed.month === "string" ? parsed.month : monthKey(now),
+      records: {
+        day: Number(parsed.records?.day) || 0,
+        month: Number(parsed.records?.month) || 0,
+      },
+      spendUsd: {
+        day: Number(parsed.spendUsd?.day) || 0,
+        month: Number(parsed.spendUsd?.month) || 0,
+      },
+    };
+    return rollWindows(state, now);
+  } catch {
+    return emptyState(now);
+  }
+}
+
+export function saveMeter(state: AcquireMeterState, baseDir?: string): void {
+  const path = acquireMeterPath(baseDir);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function headroom(limit: number | undefined, used: number): number | null {
+  if (limit === undefined) return null;
+  return Math.max(0, limit - used);
+}
+
+/**
+ * Compute remaining headroom and the max additional records creatable now.
+ * `costPerRecord` (USD) converts the spend budget into a record ceiling; when
+ * it is 0 the spend budget cannot constrain record count.
+ */
+export function remaining(
+  state: AcquireMeterState,
+  budget: AcquireBudget | undefined,
+  costPerRecord: number,
+  now: Date,
+): AcquireRemaining {
+  const rolled = rollWindows(state, now);
+  const records = {
+    day: headroom(budget?.records?.perDay, rolled.records.day),
+    month: headroom(budget?.records?.perMonth, rolled.records.month),
+  };
+  const spendUsd = {
+    day: headroom(budget?.spend?.perDay, rolled.spendUsd.day),
+    month: headroom(budget?.spend?.perMonth, rolled.spendUsd.month),
+  };
+
+  const ceilings: number[] = [];
+  if (records.day !== null) ceilings.push(records.day);
+  if (records.month !== null) ceilings.push(records.month);
+  if (costPerRecord > 0) {
+    if (spendUsd.day !== null) ceilings.push(Math.floor(spendUsd.day / costPerRecord));
+    if (spendUsd.month !== null) ceilings.push(Math.floor(spendUsd.month / costPerRecord));
+  }
+  const maxRecords = ceilings.length === 0 ? null : Math.max(0, Math.min(...ceilings));
+  return { records, spendUsd, maxRecords };
+}
+
+/**
+ * Record a successful batch of creates against the budget and persist.
+ * Returns the updated state. Call AFTER the writes land, so a failed apply
+ * never charges the meter.
+ */
+export function recordConsumption(
+  now: Date,
+  recordsCreated: number,
+  spendUsd: number,
+  baseDir?: string,
+): AcquireMeterState {
+  const state = loadMeter(now, baseDir);
+  const next: AcquireMeterState = {
+    day: state.day,
+    month: state.month,
+    records: {
+      day: state.records.day + recordsCreated,
+      month: state.records.month + recordsCreated,
+    },
+    spendUsd: {
+      day: state.spendUsd.day + spendUsd,
+      month: state.spendUsd.month + spendUsd,
+    },
+  };
+  saveMeter(next, baseDir);
+  return next;
+}

package/src/acquireSeen.ts

@@ -0,0 +1,57 @@
+/**
+ * The acquire "seen" cache — cross-run memory of prospects already processed,
+ * so re-running the same ICP doesn't re-pay the (expensive) email-resolution
+ * step for people we resolved last time. Keyed by stable prospect identity
+ * (LinkedIn URL, name+domain, email); a hit on ANY key means "skip before
+ * paying". Per-profile, stored under the credential home.
+ *
+ * Distinct from the meter (spend budget) and from the live-CRM dedup (the
+ * snapshot match + apply-time resolve-first): this avoids RE-spending across
+ * runs; those avoid double-creating within/against the CRM.
+ *
+ * Zero deps. Stored as { key: lastSeenISO } so the cache can be pruned by age.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { credentialsDir } from "./credentials.ts";
+
+type SeenStore = Record<string, string>;
+
+/** Keep the newest N keys; bounds the file for very large/long-running fills. */
+const SEEN_CAP = 50_000;
+
+export function acquireSeenPath(baseDir?: string): string {
+  return join(baseDir ?? credentialsDir(), "acquire", "seen.json");
+}
+
+/** Load the set of seen keys (empty if none/corrupt). */
+export function loadSeen(baseDir?: string): Set<string> {
+  try {
+    const store = JSON.parse(readFileSync(acquireSeenPath(baseDir), "utf8")) as SeenStore;
+    return new Set(Object.keys(store));
+  } catch {
+    return new Set();
+  }
+}
+
+/** Merge keys into the cache with a `now` timestamp, prune to cap, persist. */
+export function recordSeen(keys: string[], now: Date, baseDir?: string): void {
+  if (keys.length === 0) return;
+  let store: SeenStore = {};
+  try {
+    store = JSON.parse(readFileSync(acquireSeenPath(baseDir), "utf8")) as SeenStore;
+  } catch {
+    store = {};
+  }
+  const iso = now.toISOString();
+  for (const key of keys) store[key] = iso;
+
+  let entries = Object.entries(store);
+  if (entries.length > SEEN_CAP) {
+    entries = entries.sort((a, b) => (a[1] < b[1] ? 1 : -1)).slice(0, SEEN_CAP);
+    store = Object.fromEntries(entries);
+  }
+  const path = acquireSeenPath(baseDir);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(store)}\n`, "utf8");
+}