fullstackgtm 0.34.0 → 0.38.0

package/CHANGELOG.md

@@ -5,6 +5,147 @@ 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).
 
+## [Unreleased]
+
+## [0.38.0] — 2026-06-23
+
+### Added
+
+- **CLI run observability — paired CLIs report each run to the hosted dashboard.**
+  When the CLI is paired (`login --via <hosted url>`), a best-effort run record —
+  command, status (`success`/`partial`/`error`), duration, headline counts, and
+  structured events (plan saved, meter charged) — is POSTed to the deployment's
+  run timeline after each command (`runReport.ts`: `reportCounts` / `reportEvent`
+  / `flushRunReport`). Opt-in by pairing (an unpaired CLI sends nothing), 4s-capped,
+  swallows every error, and never affects the command's exit code; setup/inspection
+  verbs (`login`, `doctor`, `help`, `--version`) are skipped. The hosted dashboard
+  re-maps onto these runs (`/dashboard/runs`).
+
+- **Lead assignment — acquired leads are never born ownerless.** A shared
+  `AssignmentPolicy` (`assign.ts`: `fixed` / `round-robin` / `territory` /
+  `account-owner`) routes an owner onto every record, consumed in two places:
+  - **`enrich acquire`** stamps the resolved owner into each `create_record`
+    payload (`EnrichConfig.acquire.assign`); the HubSpot connector maps it to
+    `hubspot_owner_id` at create time. Round-robin distributes by the within-run
+    index (deterministic, no persisted cursor); every result is gated by the
+    snapshot's active owners, so an unknown/inactive owner collapses to
+    unassigned rather than writing a bad owner. The CLI defaults to the portal's
+    sole active owner when no policy is set (or `--assign-owner <id>`), and warns
+    + leaves leads unassigned when several owners exist and no policy says how to
+    route. `AcquireCounts` now reports `assigned` / `unassigned`.
+  - **`reassign --assign-unowned --to <ownerId>`** claims every existing
+    ownerless record (`ownerId:empty`) for an owner — the backfill twin of
+    acquire's create-time assignment.
+
+- **`enrich acquire --source linkedin` — governed LinkedIn lead acquisition
+  (Phase 1, discovery + dry-run).** LinkedIn is a new discovery source on the
+  existing acquire spine: it reads a pre-built **HeyReach** lead list
+  (`--list <id>` or `acquire.discovery.linkedin.listId`), normalizes leads to
+  the canonical `Prospect` type, then reuses ICP scoring, pre-email dedup, the
+  acquire meter, and the dry-run → approve → apply gate unchanged. The LinkedIn
+  profile URL is the match key; cost is `$0`/record (the list is already built).
+  - **`LinkedInProvider`** interface (`connectors/linkedin.ts`) with a default
+    **HeyReach** adapter (`HEYREACH_BASE`, `X-API-KEY`) and a
+    `FakeLinkedInProvider` so the whole pipeline runs with no key and no network.
+    `createLinkedInProvider` rejects unknown providers (`heyreach` only for now;
+    `unipile` is the planned alternative behind the same interface).
+  - Auth: `login heyreach` or `HEYREACH_API_KEY`.
+  - **Read-only / no sending.** Phase 1 is discovery only — no
+    `linkedin_connect` / `linkedin_message` operations, no webhook ingestion
+    (Phase 2). Without `--save` nothing is written and there is zero send/ToS
+    exposure.
+
+## [0.37.0] — 2026-06-19
+
+### Added
+
+- **`enrich acquire` — net-new, ICP-targeted, deduped, metered lead generation
+  into the CRM.** Where `enrich append/refresh` fill blanks on records that
+  already exist, `acquire` discovers net-new people, resolves their work email,
+  and proposes governed `create_record` operations through the existing
+  dry-run → approve → apply gate. Never auto-writes.
+  - **`create_record` operation** + resolve-first contact creation in the
+    HubSpot connector (re-checks the dedupe key at apply, never double-creates).
+  - **Acquire meter** (`acquireMeter.ts`): per-profile windowed budget capping
+    both record count and provider spend (per-day + per-month, whichever binds
+    first); charged only for creates that land at apply.
+  - **ICP artifact** (`icp.ts`) + **`icp interview` / `icp set` / `icp show`**:
+    one profile drives per-provider discovery filters (Explorium + pipe0/Crustdata)
+    AND fit-scores every prospect — only above-threshold leads are proposed.
+    `icp interview` emits a question spec an agent drives with AskUserQuestion.
+  - **API prospect sources** (`connectors/prospectSources.ts`): Explorium
+    discovery, pipe0 work-email waterfall (chunked, surfaces upstream errors),
+    and pipe0/Crustdata people search.
+  - **No paying for dupes**: pre-email dedup against the live CRM snapshot +
+    a cross-run **seen cache** (`acquireSeen.ts`) drop already-known prospects
+    *before* the paid email step. **LinkedIn URL (`hs_linkedin_url`) is now read
+    into the snapshot** as the strong dedup key (safe everywhere — HubSpot
+    ignores unknown properties); created contacts write it back, so dedup
+    strengthens over time. A recommendation fires when the CRM has none.
+  - **Zero-config preset**: `enrich acquire` works with only an `icp.json` and
+    `login` — sensible defaults for budget, provider, and create-mapping.
+  - **`login pipe0` / `login explorium`** credential flow.
+
+### Also
+
+- Built-in **clay enrich preset** + `enrich ingest <csv> --source clay --input`
+  one-shot (stage → match in one command).
+
+## [0.36.0] — 2026-06-19
+
+### Added
+
+- **Engagement workspace — a per-client CRM health timeline.** The profile dir
+  (`$FSGTM_HOME[/profiles/<name>]`) becomes a continuous record, not just a place
+  for credentials and plans: every `audit --save` now stamps a deterministic
+  hygiene score and a snapshot onto the profile, so a consultant working
+  `--profile <client>` accrues that org's health over time from the verb they
+  already run.
+  - **`fullstackgtm health [--json]`** (new, read-only) rolls up the timeline:
+    current score, the change since the last audit, a dated trend, and per-rule
+    finding deltas. Empty timeline prints a pointer, never an error.
+  - **Deterministic score** = `100 / (1 + severity-weighted findings per record)`
+    (info ×1, warning ×3, critical ×10): 0 findings ⇒ 100; the same findings over
+    fewer clean records score lower. No LLM — stable in CI, comparable run-over-run.
+  - New library exports `computeHealth`, `summarizeHealth`, `healthToMarkdown`
+    and the `HealthEntry` / `HealthRollup` / `HealthRuleDelta` types.
+  - State is profile-scoped and owner-only (0600): `health.jsonl` (append-only)
+    and `snapshots/<planId>.json`, alongside `plans/` under the same secured dir.
+
+## [0.35.0] — 2026-06-19
+
+### Added
+
+- **Progressive-disclosure help.** The front door is now a lifecycle-grouped map
+  (Setup · Detect · Prevent · Remediate · Calls · Govern · Market · Schedule) of
+  ~one line per verb instead of a 194-line wall — bare invoke and `--help` print
+  it. `<verb> --help` gives focused per-command help (summary, synopsis, key
+  options, the verb's lifecycle phase, see-also) rather than the whole surface.
+  New `help [command] [--full]` command; `--full` always escapes to the complete
+  reference. `call`/`market`/`enrich`/`bulk-update`/`schedule` keep their own
+  richer help.
+- **`audit` next-step guidance.** After a human-readable audit, the CLI prints a
+  context-aware next step on stderr (so stdout stays clean for pipes/`--out`):
+  the demo points to `report --demo` and `login`; a saved live audit chains
+  `suggest → plans approve → apply` with the real plan id; a clean snapshot
+  points to `resolve`/`schedule`. Suppressed under `--json`.
+- **`audit --full`** and **`patchPlanToMarkdown(plan, { summary })`** — a summary
+  view (header + Findings-by-Rule table + operation count) for read-side audits.
+
+### Changed
+
+- **`audit` defaults to the summary view** (≈24 lines on the demo vs ≈1,470
+  before); `--full` opts into the per-operation dump. The default stays full for
+  write-preview renders (`bulk-update`, `fix`, `dedupe`, `plans show`, MCP), where
+  you approve specific operations and want every operation's detail. The `--json`
+  machine output is unchanged.
+- **Plan footer reframed** from "This prototype is dry-run only…" to the actual
+  safety invariants ("Dry-run plan — read-only. No provider write happens until
+  you approve specific operations and run `apply`… These safety invariants are
+  not beta."), matching the README and agent skill.
+
+See [docs/dx-punch-list.md](./docs/dx-punch-list.md) for the audit that drove this.
+
 ## [0.34.0] — 2026-06-18
 
 ### Added

package/INSTALL_FOR_AGENTS.md

@@ -69,6 +69,14 @@ the environment, or have the human run `echo "$KEY" | fullstackgtm login apollo`
 once. Without it, `enrich ingest <file> --source clay` still stages push-style
 data keyless.
 
+`enrich acquire` differs from `append`/`refresh`: instead of filling blanks on
+existing records it creates net-new, ICP-targeted leads via governed
+`create_record` plans (resolve-first dedupe re-checks the key at apply, never
+double-creates) and is capped by a per-profile windowed meter bounding record
+count and provider spend per day and per month. It still flows through
+dry-run → approve → apply and never auto-writes — expect it to refuse rather
+than silently exceed the meter.
+
 Provider prerequisites (what the human must create, and which scopes) are in
 the README's **"Connect your CRM"** section: HubSpot needs a private app with
 four `crm.objects.*.read` scopes (plus write scopes only for `apply`);

package/README.md

@@ -128,6 +128,7 @@ fullstackgtm bulk-update deal --where "stage=closedwon" --where "amount:empty" \
   --set amount=from:account.annualrevenue --save     # per-record derived values; empty sources skipped, never guessed
 fullstackgtm dedupe account --key domain --keep richest --save   # one merge_records op per duplicate group
 fullstackgtm reassign --from 411 --to 902 --except-deal-stage closing --save   # ownership handoff playbook
+fullstackgtm reassign --assign-unowned --to 902 --save          # claim every ownerless record for an owner
 fullstackgtm fix --rule missing-deal-owner --provider hubspot --yes  # audit one rule → suggest → approve → apply, one command
 ```
 
@@ -169,6 +170,42 @@ fullstackgtm enrich status --runs                           # last run per sourc
 
 Matching is deterministic: ordered keys, unique hit wins, zero hits falls through to the next key, and multiple hits are never guessed away — they skip (recorded with candidate ids) or flow into the existing `suggest` → `plans approve` chain as `requires_human_record_selection` placeholders. The MVP conflict policy is `never`: enrich only fills blank fields, and `refresh` only re-touches fields its own run-store ledger proves it stamped (per-record/per-field `enrichedAt`, profile-scoped, never written into your portal as custom properties). The `system-only` and `always` rungs of the ladder are phase 2 and are refused explicitly, not silently accepted. Recurring execution belongs to the scheduler — enrich owns no cron logic.
 
+## Acquire: net-new leads, ICP-targeted and dupe-safe by default
+
+`enrich append/refresh` fill blanks on records you already have. **`enrich acquire`** creates *net-new* ones — and routes them through the same dry-run → approve → apply gate, so prospecting can never silently write to your CRM. It discovers people, resolves their work email, scores them against your ICP, dedupes against your CRM, and proposes governed `create_record` operations.
+
+```bash
+fullstackgtm icp interview                                  # emit the ICP question spec; an agent asks it (AskUserQuestion)
+fullstackgtm icp set answers.json --name "RevOps ICP"       # write icp.json (firmographics + persona + fit threshold)
+echo "$PIPE0_API_KEY" | fullstackgtm login pipe0            # discovery + work-email provider, stored 0600
+
+fullstackgtm enrich acquire --provider hubspot              # zero-config: ICP → discover → score → dedup → dry-run diff
+fullstackgtm enrich acquire --provider hubspot --max 25 --save   # cap the batch, persist the needs_approval plan
+fullstackgtm plans approve <id> --operations all
+fullstackgtm apply --plan-id <id> --provider hubspot        # the only step that creates contacts
+```
+
+The **ICP** (`icp.json`) is the single targeting artifact: it generates each provider's discovery filters (Explorium, pipe0/Crustdata) *and* fit-scores every discovered prospect — only above-threshold leads are proposed. Develop one by interview; the CLI can't run `AskUserQuestion` itself, so `icp interview` emits the spec and an agent (Claude Code / Codex) drives it.
+
+**You don't pay to re-discover dupes.** Before the (credit-spending) email step, acquire drops prospects already in your CRM and any seen in a prior run:
+
+- **Pre-email CRM dedup** matches the live snapshot. The LinkedIn URL (`hs_linkedin_url`, read into the snapshot by default — safe everywhere, HubSpot ignores unknown properties) is the strong key; name+domain is the fallback. Created contacts get their LinkedIn URL written back, so coverage — and dedup precision — grows over time. If your CRM has no LinkedIn URLs, acquire says so and recommends populating it.
+- **A cross-run seen cache** remembers everyone already resolved, so re-running the same ICP costs nothing for known people.
+- Two more checkpoints stay precise: the email-level match at plan build, and **resolve-first at apply** (re-checks the live CRM, never double-creates, never charges the meter).
+
+Every run is **metered**: a per-profile budget caps both record count and provider spend (per-day + per-month, whichever binds first), charged only for creates that actually land. `enrich acquire` runs with just an `icp.json` and a `login` — sensible defaults for budget, provider, and create-mapping ship in the box.
+
+**Discovery sources** are zero-config presets behind `--source`: `explorium` and `pipe0` run ICP-driven people search, while `linkedin` (Phase 1 — discovery + dry-run) reads a pre-built **HeyReach** lead list:
+
+```bash
+echo "$HEYREACH_API_KEY" | fullstackgtm login heyreach        # or set HEYREACH_API_KEY
+fullstackgtm enrich acquire --source linkedin --list <listId> --provider hubspot   # score → dedup → dry-run diff
+```
+
+LinkedIn is just another discovery source on the same scored → deduped → metered → dry-run→approve→apply spine; the LinkedIn profile URL is the match key and the list costs `$0`/record. **It never sends** — connect/message operations are out of scope for Phase 1, so without `--save` there is zero send/ToS exposure.
+
+**Leads are never born ownerless.** An `acquire.assign` policy stamps an owner onto every created lead at create time (mapped to HubSpot `hubspot_owner_id`), routed by one of four strategies — `fixed`, `round-robin` (distributed deterministically, no rotation state to drift), `territory` (by geo / industry / size / department / title), or `account-owner` (inherit the matched company's owner). With no policy and a single-owner portal, acquire defaults every lead to that owner (or pass `--assign-owner <id>`); with multiple owners and no policy it warns and leaves them unassigned rather than guess. To clear *existing* ownerless records, `reassign --assign-unowned --to <ownerId>` applies the same intent as a backfill.
+
 ## Schedules: declare a cadence once, keep the governance contract under automation
 
 Everything the CLI produces is accurate the moment it runs and silently stale afterward. The **schedule layer** is the horizontal fix — any read/plan-side command on a cron cadence, one component, every verb (no feature owns its own cron logic):
@@ -246,6 +283,8 @@ fullstackgtm login --via https://gtm.yourco.com
 
 An admin connects HubSpot **once** in the hosted dashboard (the org's OAuth tokens live encrypted in the deployment). Pairing a CLI is a device-flow handshake: the CLI prints a code, an admin or manager approves it in the dashboard, and the CLI receives a long-lived broker token (stored hashed server-side, revocable per CLI). From then on, every provider command silently exchanges the broker token for a short-lived CRM access token minted from the org's stored sync credentials — and inherits the org's field mappings. No one pastes CRM tokens; revoking a laptop is one row.
 
+**Run observability (paired CLIs).** Once paired, each command best-effort reports a run record — command, status (`success`/`partial`/`error`), duration, headline counts (e.g. ops emitted, leads created, est. cost), and structured events (plan saved, meter charged) — to the deployment's **run timeline** in the dashboard. It's opt-in by pairing (an unpaired CLI sends nothing), a 4-second-capped POST that swallows every error, and never changes the command's exit code. Setup/inspection verbs (`login`, `doctor`, `help`, `--version`) are skipped.
+
 ### Individuals: no deployment needed
 
 ```bash

package/dist/acquireLinkedIn.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 { 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 declare function linkedInProspectToProspect(lp: LinkedInProspect): Prospect;
+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 declare function discoverLinkedInProspects(provider: LinkedInProvider, options?: DiscoverLinkedInOptions): Promise<Prospect[]>;
+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 declare function createLinkedInProvider(source: string, apiKey: string, options?: CreateLinkedInProviderOptions): LinkedInProvider;

package/dist/acquireLinkedIn.js

@@ -0,0 +1,57 @@
+/**
+ * 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, } from "./connectors/linkedin.js";
+/** Map a normalized LinkedIn prospect into the canonical acquire `Prospect`. */
+export function linkedInProspectToProspect(lp) {
+    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,
+    };
+}
+/**
+ * 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, options = {}) {
+    const raw = await provider.fetchProspects({ sourceId: options.sourceId, max: options.max });
+    return raw.map(linkedInProspectToProspect);
+}
+/**
+ * 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, apiKey, options = {}) {
+    switch (source) {
+        case "linkedin":
+        case "heyreach":
+            return createHeyReachProvider({ apiKey, ...options });
+        default:
+            throw new Error(`Unknown LinkedIn execution provider "${source}" (supported: heyreach).`);
+    }
+}

package/dist/acquireMeter.d.ts

@@ -0,0 +1,67 @@
+/** 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 declare function dayKey(now: Date): string;
+export declare function monthKey(now: Date): string;
+export declare function acquireMeterPath(baseDir?: string): string;
+/**
+ * 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 declare function rollWindows(state: AcquireMeterState, now: Date): AcquireMeterState;
+/** Load the meter from disk, rolling stale windows forward. Missing = empty. */
+export declare function loadMeter(now: Date, baseDir?: string): AcquireMeterState;
+export declare function saveMeter(state: AcquireMeterState, baseDir?: string): void;
+/**
+ * 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 declare function remaining(state: AcquireMeterState, budget: AcquireBudget | undefined, costPerRecord: number, now: Date): AcquireRemaining;
+/**
+ * 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 declare function recordConsumption(now: Date, recordsCreated: number, spendUsd: number, baseDir?: string): AcquireMeterState;

package/dist/acquireMeter.js

@@ -0,0 +1,145 @@
+/**
+ * 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.js";
+export function dayKey(now) {
+    return now.toISOString().slice(0, 10);
+}
+export function monthKey(now) {
+    return now.toISOString().slice(0, 7);
+}
+export function acquireMeterPath(baseDir) {
+    return join(baseDir ?? credentialsDir(), "acquire", "meter.json");
+}
+function emptyState(now) {
+    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, now) {
+    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, baseDir) {
+    let raw;
+    try {
+        raw = readFileSync(acquireMeterPath(baseDir), "utf8");
+    }
+    catch {
+        return emptyState(now);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const state = {
+            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, baseDir) {
+    const path = acquireMeterPath(baseDir);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+function headroom(limit, used) {
+    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, budget, costPerRecord, now) {
+    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 = [];
+    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, recordsCreated, spendUsd, baseDir) {
+    const state = loadMeter(now, baseDir);
+    const next = {
+        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/dist/acquireSeen.d.ts

@@ -0,0 +1,5 @@
+export declare function acquireSeenPath(baseDir?: string): string;
+/** Load the set of seen keys (empty if none/corrupt). */
+export declare function loadSeen(baseDir?: string): Set<string>;
+/** Merge keys into the cache with a `now` timestamp, prune to cap, persist. */
+export declare function recordSeen(keys: string[], now: Date, baseDir?: string): void;

package/dist/acquireSeen.js

@@ -0,0 +1,54 @@
+/**
+ * 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.js";
+/** Keep the newest N keys; bounds the file for very large/long-running fills. */
+const SEEN_CAP = 50_000;
+export function acquireSeenPath(baseDir) {
+    return join(baseDir ?? credentialsDir(), "acquire", "seen.json");
+}
+/** Load the set of seen keys (empty if none/corrupt). */
+export function loadSeen(baseDir) {
+    try {
+        const store = JSON.parse(readFileSync(acquireSeenPath(baseDir), "utf8"));
+        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, now, baseDir) {
+    if (keys.length === 0)
+        return;
+    let store = {};
+    try {
+        store = JSON.parse(readFileSync(acquireSeenPath(baseDir), "utf8"));
+    }
+    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");
+}