fullstackgtm 0.42.0 → 0.44.0

package/src/schedule.ts

@@ -84,7 +84,13 @@ const SCHEDULABLE: Record<string, string[] | null> = {
   suggest: null,
   report: null,
   doctor: null,
-  enrich: ["append", "refresh"],
+  // `enrich append|refresh` fill blanks; `enrich acquire` creates net-new
+  // leads — but ONLY as a needs_approval `create_record` plan (`--save`,
+  // required below), never a write. This is what lets `tam populate` chip away
+  // at a TAM unattended: each firing queues a fresh lead plan, the meter is
+  // charged only at apply, and apply stays `apply --plan-id` (re-checked
+  // approved). So scheduled acquire accumulates proposals, never surprise leads.
+  enrich: ["append", "refresh", "acquire"],
   market: ["capture", "refresh"],
   // The GTM brain. `signals fetch` is read-only re: CRM (--save persists only
   // the local signal ledger). `icp judge`/`icp eval` are read-only/grade-only
@@ -98,9 +104,9 @@ const SCHEDULABLE: Record<string, string[] | null> = {
 };
 
 const ALLOWLIST_SUMMARY =
-  "audit, snapshot, enrich append|refresh, market capture|refresh, signals fetch, " +
-  "icp judge|eval, draft (stages a plan), suggest, report, doctor — " +
-  "plus apply --plan-id <id> (re-checked approved at every firing)";
+  "audit, snapshot, enrich append|refresh, enrich acquire --save (stages a lead plan), " +
+  "market capture|refresh, signals fetch, icp judge|eval, draft (stages a plan), " +
+  "suggest, report, doctor — plus apply --plan-id <id> (re-checked approved at every firing)";
 
 /**
  * Validate that an argv resolves to a schedulable fullstackgtm command.
@@ -158,6 +164,16 @@ export function validateSchedulableArgv(argv: string[]): void {
           .join(", ")}.`,
       );
     }
+    // `enrich acquire` is schedulable ONLY in its plan-producing form: without
+    // --save it's a dry-run that writes nothing AND queues nothing, so an
+    // unattended firing would silently no-op. Require --save so a scheduled
+    // acquire always leaves a needs_approval plan behind (apply stays gated).
+    if (head === "enrich" && sub === "acquire" && !argv.includes("--save")) {
+      throw new Error(
+        "Scheduled `enrich acquire` must include --save so each firing queues a needs_approval lead plan " +
+          "(without it the run produces nothing). Apply stays a separate human gate (`apply --plan-id <id>`).",
+      );
+    }
   }
 }
 

package/src/signals.ts

@@ -65,6 +65,9 @@ export type SignalOutcome = {
   id: string;
   accountDomain: string;
   touchId?: string;
+  /** The contact the touch went to (from the judge decision), when known — so an
+   *  outcome credits the person reached, not just the account domain. */
+  contactId?: string;
   result: SignalOutcomeResult;
   recordedAt: string;
   /** Signal ids credited (from the judge decision). */
@@ -413,6 +416,71 @@ function withinWindow(iso: string, now: Date, windowDays: number): boolean {
   return now.getTime() - t <= windowDays * DAY_MS;
 }
 
+// ---------------------------------------------------------------------------
+// Staged rows -> signals (shared by `--from` ingest and source connectors)
+
+/**
+ * One staged signal row: the platform-agnostic intake shape every NON-job source
+ * produces (a source connector's output, or a `--from` JSON row). It carries the
+ * evidence anchor (`quote`) but none of the derived fields (`id`, `weight`,
+ * `source`) — `stagedRowToSignal` fills those so there is ONE place that gates
+ * evidence and stamps identity, whether the row came from a file or an API.
+ */
+export type StagedSignalRow = {
+  bucket: SignalBucket;
+  accountDomain: string;
+  trigger: string;
+  /** VERBATIM evidence — required, non-empty. */
+  quote: string;
+  sourceUrl?: string;
+  /** ISO 8601; defaults to run time when absent. */
+  firstSeen?: string;
+  /** Optional explicit weight; defaults to the bucket's configured weight. */
+  weight?: number;
+};
+
+/**
+ * Validate one loosely-typed staged row and turn it into a `Signal`, applying
+ * the verbatim-evidence gate (a row with no quote is rejected, never faked) and
+ * the same id/normalization logic the ATS path uses. `errorLabel` lets the
+ * caller produce a precise message ("--from f.json: row 3", "serpapi-news row 0")
+ * since both the `--from` ingest and the source-connector registry funnel here.
+ *
+ * Throws on a malformed row; returns the canonical `Signal` on success. Bucket
+ * FILTERING (skip rows outside a `--bucket` selection) stays with the caller —
+ * this function is per-row validation only.
+ */
+export function stagedRowToSignal(
+  entry: Record<string, unknown>,
+  opts: { now: Date; source: string; errorLabel: string },
+): Signal {
+  const { now, source, errorLabel } = opts;
+  const bucket = String(entry.bucket ?? "");
+  if (!SIGNAL_BUCKETS.includes(bucket as SignalBucket)) {
+    throw new Error(`${errorLabel} has unknown bucket "${bucket}" (one of ${SIGNAL_BUCKETS.join(", ")}).`);
+  }
+  const accountDomain = normalizeAccountDomain(String(entry.accountDomain ?? entry.domain ?? ""));
+  if (!accountDomain) throw new Error(`${errorLabel} is missing accountDomain.`);
+  const trigger = String(entry.trigger ?? "").trim();
+  if (!trigger) throw new Error(`${errorLabel} is missing trigger.`);
+  const quote = String(entry.quote ?? "").trim();
+  if (!quote) throw new Error(`${errorLabel} is missing the verbatim quote (the evidence anchor).`);
+  const base = { accountDomain, bucket: bucket as SignalBucket, trigger };
+  const firstSeen = typeof entry.firstSeen === "string" && entry.firstSeen ? entry.firstSeen : now.toISOString();
+  return {
+    id: signalId(base),
+    accountDomain,
+    bucket: bucket as SignalBucket,
+    trigger,
+    quote,
+    sourceUrl: String(entry.sourceUrl ?? ""),
+    firstSeen,
+    weight: typeof entry.weight === "number" ? entry.weight : DEFAULT_SIGNALS_CONFIG.buckets[bucket as SignalBucket].weight,
+    source,
+    judgedBy: null,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Dedup
 
@@ -530,6 +598,31 @@ export function signalsDir(baseDir?: string): string {
   return join(baseDir ?? credentialsDir(), "signals");
 }
 
+/**
+ * Conventional webhook landing zone: `<signals>/spool`, profile-scoped. A
+ * webhook receiver (hosted, or the operator's own glue) appends one JSONL row
+ * per event to a `*.jsonl` file here; `signals fetch --connector file` reads the
+ * whole directory when given no explicit path. The CLI never writes here — the
+ * receiver does — so this is just the agreed-upon location, not a managed store.
+ * Per-source files (`rb2b.jsonl`, `hubspot.jsonl`, …) coexist. See
+ * docs/signal-spool-format.md.
+ */
+export function signalsSpoolDir(baseDir?: string): string {
+  return join(signalsDir(baseDir), "spool");
+}
+
+/**
+ * Conventional outbox: `<signals>/outbox`, profile-scoped — the SEND-side mirror
+ * of the spool. `apply --channel outbox` renders each APPROVED drafted opener to
+ * a `<channel>.jsonl` file here (one row per touch); a downstream sender (hosted,
+ * or the operator's own) drains it. The CLI WRITES governed, approved send
+ * intents here but TRANSMITS NOTHING — the "drafts everything, transmits nothing"
+ * invariant holds. See docs/outbox-format.md.
+ */
+export function signalsOutboxDir(baseDir?: string): string {
+  return join(signalsDir(baseDir), "outbox");
+}
+
 export type SignalRun = {
   id: string;
   runLabel: string;
@@ -668,6 +761,7 @@ export function createFileSignalStore(directory?: string): SignalStore {
 export function makeOutcome(input: {
   accountDomain: string;
   touchId?: string;
+  contactId?: string;
   result: SignalOutcomeResult;
   creditedSignals?: string[];
   recordedAt?: string;
@@ -678,6 +772,7 @@ export function makeOutcome(input: {
     id: outcomeId({ accountDomain, touchId: input.touchId, result: input.result, recordedAt }),
     accountDomain,
     ...(input.touchId !== undefined ? { touchId: input.touchId } : {}),
+    ...(input.contactId !== undefined ? { contactId: input.contactId } : {}),
     result: input.result,
     recordedAt,
     creditedSignals: input.creditedSignals ?? [],