fullstackgtm 0.43.0 → 0.45.0

package/dist/schedule.js

@@ -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.js";
 // Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep schedule.ts
@@ -29,7 +30,13 @@ const SCHEDULABLE = {
     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
@@ -41,9 +48,9 @@ const SCHEDULABLE = {
     icp: ["judge", "eval"],
     draft: 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)";
+const ALLOWLIST_SUMMARY = "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.
  * Enforced at `schedule add` time AND re-checked at `schedule run` time (the
@@ -89,6 +96,14 @@ export function validateSchedulableArgv(argv) {
                 .map((name) => `${head} ${name}`)
                 .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>`).");
+        }
     }
 }
 /**
@@ -578,3 +593,255 @@ export function replaceManagedBlock(existing, profile, block) {
         return "";
     return `${merged.join("\n")}\n`;
 }
+/**
+ * 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, cap = 512) {
+    const full = (values, min, max) => values.length === max - min + 1;
+    const minutes = full(cron.minute, 0, 59) ? [undefined] : cron.minute;
+    const hours = full(cron.hour, 0, 23) ? [undefined] : cron.hour;
+    const months = 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 = [];
+    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 = [];
+    for (const month of months) {
+        for (const daySlot of daySlots) {
+            for (const hour of hours) {
+                for (const minute of minutes) {
+                    const dict = {};
+                    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, firedAt) {
+    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) {
+    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, scheduleEntryId) {
+    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) {
+    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) {
+    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"];
+    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`;
+}
+/**
+ * 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) {
+    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) => {
+        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, entries, cliArgv, io, options = {}) {
+    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 = [];
+    for (const entry of entries) {
+        assertRenderableEntry(profile, entry);
+        let intervals;
+        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, io) {
+    const prefix = launchdAgentPrefix(profile);
+    const removed = [];
+    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/dist/signals.d.ts

@@ -132,6 +132,41 @@ export declare function buildSignalsFromAts(rawJobs: Array<AtsJob & {
     now?: Date;
     priorSignals?: Signal[];
 }): Signal[];
+/**
+ * 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 declare function stagedRowToSignal(entry: Record<string, unknown>, opts: {
+    now: Date;
+    source: string;
+    errorLabel: string;
+}): Signal;
 /**
  * Split candidate signals into fresh vs. deduped against prior signals. A
  * candidate is deduped when a prior signal shares its `dedupKey`
@@ -160,6 +195,25 @@ export declare function dedupeSignals(candidates: Signal[], priorSignals: Signal
  */
 export declare function computeWeights(config: SignalsConfig, outcomes: SignalOutcome[], signalsById?: Map<string, Signal>): Record<SignalBucket, number>;
 export declare function signalsDir(baseDir?: string): string;
+/**
+ * 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 declare function signalsSpoolDir(baseDir?: string): string;
+/**
+ * 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 declare function signalsOutboxDir(baseDir?: string): string;
 export type SignalRun = {
     id: string;
     runLabel: string;

package/dist/signals.js

@@ -292,6 +292,47 @@ function withinWindow(iso, now, windowDays) {
         return false;
     return now.getTime() - t <= windowDays * DAY_MS;
 }
+/**
+ * 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, opts) {
+    const { now, source, errorLabel } = opts;
+    const bucket = String(entry.bucket ?? "");
+    if (!SIGNAL_BUCKETS.includes(bucket)) {
+        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, trigger };
+    const firstSeen = typeof entry.firstSeen === "string" && entry.firstSeen ? entry.firstSeen : now.toISOString();
+    return {
+        id: signalId(base),
+        accountDomain,
+        bucket: bucket,
+        trigger,
+        quote,
+        sourceUrl: String(entry.sourceUrl ?? ""),
+        firstSeen,
+        weight: typeof entry.weight === "number" ? entry.weight : DEFAULT_SIGNALS_CONFIG.buckets[bucket].weight,
+        source,
+        judgedBy: null,
+    };
+}
 // ---------------------------------------------------------------------------
 // Dedup
 /**
@@ -392,6 +433,29 @@ function blankCounts() {
 export function signalsDir(baseDir) {
     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) {
+    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) {
+    return join(signalsDir(baseDir), "outbox");
+}
 export function signalRunId(runLabel) {
     return `sigr_${fnv1a(runLabel)}`;
 }

package/dist/spoolFiles.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+/** Spool files in a landing-zone directory: `*.jsonl` / `*.json`, name-sorted. */
+export declare function spoolFilesIn(dir: string): string[];
+/** Parse a JSON-array spool file into rows. `label` prefixes error messages. */
+export declare function parseSpoolArray(raw: string, path: string, label: string): Record<string, unknown>[];
+/** Parse a JSONL spool file into rows. `label` prefixes error messages. */
+export declare function parseSpoolJsonl(raw: string, path: string, label: string): Record<string, unknown>[];
+/** Parse one spool file's text — JSON array if it opens with `[`, else JSONL. */
+export declare function parseSpoolText(raw: string, path: string, label: string): Record<string, unknown>[];
+/**
+ * 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 declare function isSpoolPath(absPath: string): boolean;
+/** 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 declare function readSpoolPath(absPath: string, label: string): SpoolRow[];

package/dist/spoolFiles.js

@@ -0,0 +1,114 @@
+/**
+ * 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) {
+    let names;
+    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, path, label) {
+    let parsed;
+    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;
+    });
+}
+/** Parse a JSONL spool file into rows. `label` prefixes error messages. */
+export function parseSpoolJsonl(raw, path, label) {
+    const out = [];
+    const lines = raw.split("\n");
+    lines.forEach((line, index) => {
+        const t = line.trim();
+        if (!t)
+            return;
+        let parsed;
+        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);
+    });
+    return out;
+}
+/** Parse one spool file's text — JSON array if it opens with `[`, else JSONL. */
+export function parseSpoolText(raw, path, label) {
+    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) {
+    try {
+        if (statSync(absPath).isDirectory())
+            return true;
+    }
+    catch {
+        return false;
+    }
+    return absPath.endsWith(".jsonl");
+}
+/**
+ * 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, label) {
+    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 = [];
+    for (const file of files) {
+        const raw = readFileSync(file, "utf8");
+        parseSpoolText(raw, file, label).forEach((row, index) => rows.push({ file, index, row }));
+    }
+    return rows;
+}