fullstackgtm 0.43.0 → 0.45.0

package/src/schedule.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.ts";
 
@@ -49,9 +50,11 @@ export type ScheduleRunRecord = {
    * recorded for visibility but nothing ran. Reasons: "plan_not_approved"
    * (scheduled apply against a plan that is not approved — there is no flag
    * that relaxes this), "not_schedulable" (the stored argv no longer passes
-   * the allowlist, e.g. after a hand edit of schedules.json).
+   * the allowlist, e.g. after a hand edit of schedules.json),
+   * "duplicate_firing" (a cron-triggered run already recorded in this minute
+   * — launchd can double-trigger the Vixie dom+dow OR corner).
    */
-  noopReason?: "plan_not_approved" | "not_schedulable";
+  noopReason?: "plan_not_approved" | "not_schedulable" | "duplicate_firing";
 };
 
 // Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep schedule.ts
@@ -84,7 +87,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 +107,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 +167,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>`).",
+      );
+    }
   }
 }
 
@@ -713,3 +732,307 @@ export function replaceManagedBlock(existing: string, profile: string, block: st
   if (merged.length === 0) return "";
   return `${merged.join("\n")}\n`;
 }
+
+// ---------------------------------------------------------------------------
+// Local provider: launchd LaunchAgents (macOS)
+//
+// On macOS `crontab -` writes to the TCC-protected /var/at/tabs, which
+// requires granting Full Disk Access to the *terminal app* — a permission no
+// program can request and a huge over-grant for one timer line. Per-user
+// LaunchAgents need no permission at all: one plist per enabled entry in
+// ~/Library/LaunchAgents, loaded with `launchctl bootstrap gui/<uid>`. Bonus
+// over cron: launchd coalesces firings missed while asleep into one run on
+// wake, where cron silently skips. Same audit story as the crontab block —
+// every plist's ProgramArguments is `... schedule run <id>` and nothing else,
+// and install replaces the com.fullstackgtm.<profile>.* fleet wholesale.
+
+/**
+ * One launchd StartCalendarInterval dict: every present key must match (AND),
+ * a missing key is a wildcard, and an array of dicts fires when ANY dict
+ * matches. Weekday 0 is Sunday, as in cron.
+ */
+export type LaunchdCalendarInterval = {
+  Minute?: number;
+  Hour?: number;
+  Day?: number;
+  Weekday?: number;
+  Month?: number;
+};
+
+/**
+ * Compile a cron expression to StartCalendarInterval dicts. Full-range fields
+ * (`*`, but also spellings like `0-59`) are omitted (launchd wildcard); the
+ * rest cross-product, capped so a dense expression cannot render a megabyte
+ * plist. Vixie day semantics: when day-of-month AND day-of-week are both
+ * restricted, either may match — launchd ANDs keys within one dict, so that
+ * becomes the union of a Day dict set and a Weekday dict set. A date matching
+ * both sets makes launchd trigger twice in the same minute; the run entry
+ * point drops the second via isDuplicateCronFiring.
+ */
+export function cronToCalendarIntervals(cron: CronExpression, cap = 512): LaunchdCalendarInterval[] {
+  const full = (values: number[], min: number, max: number) => values.length === max - min + 1;
+  const minutes: Array<number | undefined> = full(cron.minute, 0, 59) ? [undefined] : cron.minute;
+  const hours: Array<number | undefined> = full(cron.hour, 0, 23) ? [undefined] : cron.hour;
+  const months: Array<number | undefined> = full(cron.month, 1, 12) ? [undefined] : cron.month;
+  const domRestricted = cron.dayOfMonthRestricted && !full(cron.dayOfMonth, 1, 31);
+  const dowRestricted = cron.dayOfWeekRestricted && !full(cron.dayOfWeek, 0, 6);
+  const daySlots: Array<Pick<LaunchdCalendarInterval, "Day" | "Weekday">> = [];
+  if (domRestricted) for (const day of cron.dayOfMonth) daySlots.push({ Day: day });
+  if (dowRestricted) for (const weekday of cron.dayOfWeek) daySlots.push({ Weekday: weekday });
+  if (daySlots.length === 0) daySlots.push({});
+  const count = minutes.length * hours.length * daySlots.length * months.length;
+  if (count > cap) {
+    throw new Error(
+      `Cron expression "${cron.source}" expands to ${count} launchd calendar intervals (cap ${cap}). ` +
+        "Simplify the expression or split it into separate schedules.",
+    );
+  }
+  const intervals: LaunchdCalendarInterval[] = [];
+  for (const month of months) {
+    for (const daySlot of daySlots) {
+      for (const hour of hours) {
+        for (const minute of minutes) {
+          const dict: LaunchdCalendarInterval = {};
+          if (minute !== undefined) dict.Minute = minute;
+          if (hour !== undefined) dict.Hour = hour;
+          if (daySlot.Day !== undefined) dict.Day = daySlot.Day;
+          if (daySlot.Weekday !== undefined) dict.Weekday = daySlot.Weekday;
+          if (month !== undefined) dict.Month = month;
+          intervals.push(dict);
+        }
+      }
+    }
+  }
+  return intervals;
+}
+
+/**
+ * True when a cron-triggered run was already recorded in `firedAt`'s minute.
+ * The `schedule run` entry point checks this for trigger:cron so a launchd
+ * double-trigger (dom+dow OR corner above) records a duplicate_firing no-op
+ * instead of running the command twice. Manual runs are never deduplicated.
+ */
+export function isDuplicateCronFiring(runs: ScheduleRunRecord[], firedAt: string): boolean {
+  const minute = new Date(firedAt);
+  minute.setSeconds(0, 0);
+  return runs.some((run) => {
+    if (run.trigger !== "cron") return false;
+    const fired = new Date(run.firedAt);
+    fired.setSeconds(0, 0);
+    return fired.getTime() === minute.getTime();
+  });
+}
+
+/** Reverse-DNS namespace for one profile's agents; install/uninstall own this prefix wholesale. */
+export function launchdAgentPrefix(profile: string): string {
+  if (!/^[A-Za-z0-9._-]+$/.test(profile)) {
+    throw new Error(
+      `Cannot build a launchd label from profile "${profile}" — profile names in LaunchAgent labels ` +
+        "must be alphanumeric with dot/dash/underscore.",
+    );
+  }
+  return `com.fullstackgtm.${profile}.`;
+}
+
+export function launchdLabel(profile: string, scheduleEntryId: string): string {
+  if (!/^[A-Za-z0-9._-]+$/.test(scheduleEntryId)) {
+    throw new Error(`Cannot build a launchd label from schedule id "${scheduleEntryId}".`);
+  }
+  return `${launchdAgentPrefix(profile)}${scheduleEntryId}`;
+}
+
+function xmlEscape(value: string): string {
+  return value.replace(/[&<>"']/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      default:
+        return "&apos;";
+    }
+  });
+}
+
+/**
+ * Render one LaunchAgent plist. ProgramArguments is an argv array — launchd
+ * execs it directly, no shell, so there is no quoting/injection surface at
+ * all (values are XML-escaped for the document, nothing more).
+ */
+export function renderLaunchdPlist(options: {
+  label: string;
+  programArguments: string[];
+  calendarIntervals: LaunchdCalendarInterval[];
+  environment?: Record<string, string>;
+  standardOutPath?: string;
+  standardErrorPath?: string;
+}): string {
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    "\t<key>Label</key>",
+    `\t<string>${xmlEscape(options.label)}</string>`,
+    "\t<key>ProgramArguments</key>",
+    "\t<array>",
+    ...options.programArguments.map((arg) => `\t\t<string>${xmlEscape(arg)}</string>`),
+    "\t</array>",
+    "\t<key>StartCalendarInterval</key>",
+    "\t<array>",
+  ];
+  const keyOrder = ["Minute", "Hour", "Day", "Weekday", "Month"] as const;
+  for (const interval of options.calendarIntervals) {
+    lines.push("\t\t<dict>");
+    for (const key of keyOrder) {
+      const value = interval[key];
+      if (value === undefined) continue;
+      lines.push(`\t\t\t<key>${key}</key>`, `\t\t\t<integer>${value}</integer>`);
+    }
+    lines.push("\t\t</dict>");
+  }
+  lines.push("\t</array>");
+  if (options.environment && Object.keys(options.environment).length > 0) {
+    lines.push("\t<key>EnvironmentVariables</key>", "\t<dict>");
+    for (const [name, value] of Object.entries(options.environment)) {
+      lines.push(`\t\t<key>${xmlEscape(name)}</key>`, `\t\t<string>${xmlEscape(value)}</string>`);
+    }
+    lines.push("\t</dict>");
+  }
+  if (options.standardOutPath) {
+    lines.push("\t<key>StandardOutPath</key>", `\t<string>${xmlEscape(options.standardOutPath)}</string>`);
+  }
+  if (options.standardErrorPath) {
+    lines.push("\t<key>StandardErrorPath</key>", `\t<string>${xmlEscape(options.standardErrorPath)}</string>`);
+  }
+  lines.push("</dict>", "</plist>");
+  return `${lines.join("\n")}\n`;
+}
+
+export type LaunchdIo = {
+  /** Plist file names currently in the agents directory. */
+  list(): string[];
+  write(fileName: string, content: string): void;
+  remove(fileName: string): void;
+  /** Load one agent plist into the user's gui domain; throws on failure. */
+  bootstrap(fileName: string): void;
+  /** Best-effort unload by label; a label that is not loaded is not an error. */
+  bootout(label: string): void;
+};
+
+/**
+ * The real ~/Library/LaunchAgents + launchctl. Everything above takes a
+ * LaunchdIo so tests inject fakes and never touch the user's agents.
+ */
+export function systemLaunchdIo(agentsDirOverride?: string): LaunchdIo {
+  const agentsDir = agentsDirOverride ?? join(homedir(), "Library", "LaunchAgents");
+  const domain = () => {
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (uid === null) throw new Error("launchd scheduling requires a POSIX user id (macOS only).");
+    return `gui/${uid}`;
+  };
+  const launchctl = (args: string[]) => {
+    const result = spawnSync("launchctl", args, { encoding: "utf8" });
+    if (result.error) throw new Error(`Cannot run \`launchctl\`: ${result.error.message}`);
+    return result;
+  };
+  return {
+    list() {
+      try {
+        return readdirSync(agentsDir).filter((name) => name.endsWith(".plist"));
+      } catch {
+        return [];
+      }
+    },
+    write(fileName, content) {
+      mkdirSync(agentsDir, { recursive: true });
+      // 0644 like every LaunchAgent: launchd refuses group/world-WRITABLE
+      // plists, and this file holds a dispatch line, not a secret.
+      writeFileSync(join(agentsDir, fileName), content, { mode: 0o644 });
+    },
+    remove(fileName) {
+      rmSync(join(agentsDir, fileName), { force: true });
+    },
+    bootstrap(fileName) {
+      const result = launchctl(["bootstrap", domain(), join(agentsDir, fileName)]);
+      if (result.status !== 0) {
+        throw new Error(
+          `\`launchctl bootstrap\` failed for ${fileName}: ${(result.stderr ?? "").trim() || `exit ${result.status}`}`,
+        );
+      }
+    },
+    bootout(label) {
+      launchctl(["bootout", `${domain()}/${label}`]);
+    },
+  };
+}
+
+/**
+ * Materialize enabled entries as one LaunchAgent each, replacing the
+ * profile's com.fullstackgtm.<profile>.* fleet wholesale (stale agents are
+ * booted out and deleted; plists outside the prefix are never touched).
+ * `cliArgv` is the argv-array analog of the crontab invocation line.
+ */
+export function installLaunchdAgents(
+  profile: string,
+  entries: ScheduleEntry[],
+  cliArgv: string[],
+  io: LaunchdIo,
+  options: { environment?: Record<string, string>; logDir?: string } = {},
+): { installed: string[]; removed: string[] } {
+  for (const token of cliArgv) {
+    if (hasControlChar(token)) {
+      throw new Error(
+        "Refusing to render LaunchAgents: the resolved CLI invocation (node path or script path) " +
+          "contains a newline or control character.",
+      );
+    }
+  }
+  const removed = uninstallLaunchdAgents(profile, io);
+  const installed: string[] = [];
+  for (const entry of entries) {
+    assertRenderableEntry(profile, entry);
+    let intervals: LaunchdCalendarInterval[];
+    try {
+      intervals = cronToCalendarIntervals(parseCron(entry.cron));
+    } catch (error) {
+      throw new Error(
+        `Schedule ${entry.id} ("${entry.label}") cannot materialize as a LaunchAgent: ` +
+          `${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    const label = launchdLabel(profile, entry.id);
+    const logPath = options.logDir ? join(options.logDir, `${label}.log`) : undefined;
+    const plist = renderLaunchdPlist({
+      label,
+      programArguments: [...cliArgv, "schedule", "run", entry.id, "--profile", profile, "--trigger", "cron"],
+      calendarIntervals: intervals,
+      environment: options.environment,
+      standardOutPath: logPath,
+      standardErrorPath: logPath,
+    });
+    const fileName = `${label}.plist`;
+    io.write(fileName, plist);
+    io.bootstrap(fileName);
+    installed.push(label);
+  }
+  return { installed, removed };
+}
+
+/** Boot out and delete every agent in the profile's prefix; returns the removed labels. */
+export function uninstallLaunchdAgents(profile: string, io: LaunchdIo): string[] {
+  const prefix = launchdAgentPrefix(profile);
+  const removed: string[] = [];
+  for (const name of io.list()) {
+    if (!name.startsWith(prefix)) continue;
+    const label = name.slice(0, -".plist".length);
+    io.bootout(label);
+    io.remove(name);
+    removed.push(label);
+  }
+  return removed;
+}

package/src/signals.ts

@@ -416,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
 
@@ -533,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;

package/src/spoolFiles.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared reader for the spool container convention (docs/signal-spool-format.md):
+ * newline-delimited JSON — one object per line, append-only — with a JSON array
+ * accepted in a `.json` file for hand-staged convenience, and a DIRECTORY
+ * meaning "every `*.jsonl` / `*.json` file in it, name-sorted" so multiple
+ * receivers can each append their own file.
+ *
+ * The container is the convention; the row SCHEMA stays with each caller:
+ * `signals fetch --from` validates staged signal rows, `enrich ingest` stages
+ * enrichment rows, `market observe --from` validates observation-set envelopes.
+ * This module only parses objects out of files — it never interprets them.
+ *
+ * Extracted from the `file` signal-source connector (the Phase-2 webhook
+ * landing-zone reader), which now delegates here; error-message text is
+ * parameterized by `label` so existing connector errors are unchanged.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Spool files in a landing-zone directory: `*.jsonl` / `*.json`, name-sorted. */
+export function spoolFilesIn(dir: string): string[] {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((name) => name.endsWith(".jsonl") || name.endsWith(".json"))
+    .sort()
+    .map((name) => join(dir, name));
+}
+
+/** Parse a JSON-array spool file into rows. `label` prefixes error messages. */
+export function parseSpoolArray(raw: string, path: string, label: string): Record<string, unknown>[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${label} ${path}: not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+  }
+  if (!Array.isArray(parsed)) throw new Error(`${label} ${path}: expected a JSON array of staged signal rows.`);
+  return parsed.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`${label} ${path}: row ${index} is not an object.`);
+    }
+    return entry as Record<string, unknown>;
+  });
+}
+
+/** Parse a JSONL spool file into rows. `label` prefixes error messages. */
+export function parseSpoolJsonl(raw: string, path: string, label: string): Record<string, unknown>[] {
+  const out: Record<string, unknown>[] = [];
+  const lines = raw.split("\n");
+  lines.forEach((line, index) => {
+    const t = line.trim();
+    if (!t) return;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(t);
+    } catch (error) {
+      throw new Error(`${label} ${path}: line ${index} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`${label} ${path}: line ${index} is not a JSON object.`);
+    }
+    out.push(parsed as Record<string, unknown>);
+  });
+  return out;
+}
+
+/** Parse one spool file's text — JSON array if it opens with `[`, else JSONL. */
+export function parseSpoolText(raw: string, path: string, label: string): Record<string, unknown>[] {
+  const trimmed = raw.trim();
+  if (!trimmed) return [];
+  return trimmed.startsWith("[") ? parseSpoolArray(trimmed, path, label) : parseSpoolJsonl(trimmed, path, label);
+}
+
+/**
+ * Should an explicitly named intake path be read with spool semantics?
+ * True for a directory (a landing zone) or a `*.jsonl` file. Plain `.json` /
+ * `.csv` files keep each verb's original single-file handling, so existing
+ * invocations parse exactly as before.
+ */
+export function isSpoolPath(absPath: string): boolean {
+  try {
+    if (statSync(absPath).isDirectory()) return true;
+  } catch {
+    return false;
+  }
+  return absPath.endsWith(".jsonl");
+}
+
+/** A parsed spool row plus where it came from (for error labels). */
+export type SpoolRow = { file: string; index: number; row: Record<string, unknown> };
+
+/**
+ * Read an explicitly named spool path — a `.jsonl` file or a directory of
+ * `*.jsonl` / `*.json` files. Unlike the webhook `file` connector (where a
+ * missing spool is an empty source), the user named this path: a missing or
+ * unreadable file is an error, and a malformed row throws with file + line.
+ */
+export function readSpoolPath(absPath: string, label: string): SpoolRow[] {
+  const isDir = statSync(absPath).isDirectory();
+  const files = isDir ? spoolFilesIn(absPath) : [absPath];
+  if (isDir && files.length === 0) {
+    throw new Error(`${label} ${absPath}: directory contains no *.jsonl / *.json spool files.`);
+  }
+  const rows: SpoolRow[] = [];
+  for (const file of files) {
+    const raw = readFileSync(file, "utf8");
+    parseSpoolText(raw, file, label).forEach((row, index) => rows.push({ file, index, row }));
+  }
+  return rows;
+}