predictable-ai 0.1.0

package/dist/commands/bundle.js

@@ -0,0 +1,754 @@
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { CliError, EXIT } from '../errors.js';
+import { serializeCsvRows, isFormulaHazard, toCsvValue } from '../generated/csv-safety.js';
+import { classify, send } from '../http.js';
+/**
+ * `export campaign` — the spec §3.4 file bundle (ticket ga-mfacl.9 / T8,
+ * ACs 2-5 and 7).
+ *
+ * WHAT THIS IS. Seven files written to disk from six reads plus a manifest the
+ * verb core writes itself. The MCP head (T10) returns the same seven as sized
+ * tool results; that is why the assembly lives here as a function over
+ * `RequestContext` rather than inside the command dispatcher.
+ *
+ * ── THE SERIALIZER IS IMPORTED, NEVER RE-IMPLEMENTED (§5.1a) ────────────────
+ *
+ * `../generated/csv-safety.js` is a GENERATED MIRROR of
+ * `dashboard/src/lib/exa-agent/csv-safety.ts`, written by the dashboard's
+ * `generate:agent-surface` and covered by CI's generate-twice diff, exactly as
+ * `generated/commands.json` is. The CLI is a separate npm package that ships
+ * only `dist/`, so it cannot import across the repo — and a hand-written second
+ * serializer is precisely what §5.1a exists to prevent. Edit the source, never
+ * the mirror.
+ *
+ * `accounts.csv` is the exception that proves the rule: it is written BYTE FOR
+ * BYTE as the server sent it. `GET /api/export/[icpId]` already serializes
+ * through the same module (T8's re-cut), so re-serializing here would parse and
+ * re-emit CSV that was already correct — two chances to get it wrong instead of
+ * none, and it would drop the server's own hazard neutralization on the floor
+ * if the parse disagreed.
+ */
+// ── The envelope (spec §3.4, D-f drafting numbers) ──────────────────────────
+/**
+ * Caps, overridable from the environment so AC4 can breach them without
+ * writing a quarter-million rows.
+ *
+ * The override is read at CALL time, not at module load: a test that sets the
+ * variable after importing this module must still see it, and a module-level
+ * constant would have frozen the production number into the test process.
+ */
+export function envelopeCaps(env) {
+    const rows = Number(env.PREDICTABLE_BUNDLE_MAX_ROWS);
+    const bytes = Number(env.PREDICTABLE_BUNDLE_MAX_BYTES);
+    return {
+        maxRows: Number.isInteger(rows) && rows > 0 ? rows : 250_000,
+        maxBytes: Number.isInteger(bytes) && bytes > 0 ? bytes : 100 * 1024 * 1024,
+    };
+}
+/**
+ * The seven files, in one place.
+ *
+ * The list is the spec's table and the manifest's `files` key reads it, so a
+ * file added to the bundle cannot be forgotten in the manifest — and AC2's
+ * completeness check compares the directory against THIS, not against a second
+ * hand-written list of seven names.
+ */
+export const BUNDLE_FILES = [
+    'accounts.csv',
+    'contacts.csv',
+    'sequence.json',
+    'events.csv',
+    'replies.json',
+    'stats.json',
+    'manifest.json',
+];
+/** The export purposes `GET /api/export/[icpId]` accepts (§6). */
+export const EXPORT_PURPOSES = ['prospecting_activation', 'reporting_history'];
+/**
+ * The `X-Export-*` response headers `accounts.csv` carries, recorded in the
+ * manifest (AC2). Read off the RESPONSE, never recomputed here: they are the
+ * server's own count of what its suppression filter excluded, and a second
+ * derivation on the client would be a different number wearing the same name.
+ */
+export const EXPORT_HEADER_KEYS = [
+    'x-export-purpose',
+    'x-export-eligible-count',
+    'x-export-excluded-person-suppression',
+    'x-export-excluded-organization-suppression',
+    'x-export-excluded-automatic-safety',
+    'x-export-excluded-total',
+    // THE PRODUCER'S OWN HAZARD COUNT (r2 finding 6). accounts.csv is held as
+    // verbatim server bytes and this bundle never parses it, so the only honest
+    // source for "how many cells in accounts.csv were neutralized" is the route
+    // that serialized them. It reports the number here.
+    'x-export-formula-hazard-count',
+];
+/** contacts.csv's columns — a closed, named set, header row included. */
+export const CONTACT_COLUMNS = [
+    'contact_id',
+    'name',
+    'title',
+    'email',
+    'zerobounce_status',
+    'linkedin_url',
+    'phone',
+    'company_name',
+    'company_domain',
+    'tier',
+];
+/** events.csv's columns. `actor` is flattened to its two fields, not joined. */
+export const EVENT_COLUMNS = [
+    'contact_id',
+    'kind',
+    'channel',
+    'sequence_step',
+    'sent_at',
+    'actor_type',
+    'actor_id',
+];
+export class EnvelopeExceeded extends CliError {
+    file;
+    constructor(file, detail) {
+        super(EXIT.USAGE, 'bundle_envelope_exceeded', `${file}: ${detail}`);
+        this.name = 'EnvelopeExceeded';
+        this.file = file;
+    }
+}
+// ── Reads ───────────────────────────────────────────────────────────────────
+async function getJson(ctx, path, query) {
+    const call = { method: 'GET', path, ...(query ? { query } : {}) };
+    const response = await send(ctx, call);
+    const failure = classify(response, call);
+    if (failure)
+        throw failure;
+    try {
+        return JSON.parse(response.text);
+    }
+    catch {
+        throw new CliError(EXIT.SERVER, `error: ${path} did not return JSON`, `GET ${path}`);
+    }
+}
+async function readStatsSource(ctx, path, query) {
+    try {
+        return { ok: true, data: await getJson(ctx, path, query) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            unavailable: err instanceof CliError ? err.message : String(err),
+        };
+    }
+}
+/**
+ * THE REQUEST SHAPE EVERY §3.4 SOURCE IS ASKED IN, READ OFF THE ROUTE HANDLER
+ * (r3 item R2-1).
+ *
+ * WHAT WENT WRONG. Round 2 called `/api/billing/usage` with no query. That
+ * route reads `searchParams.get('icpId')` and answers 404 when it is absent
+ * (billing/usage/route.ts:36-37), so EVERY bundle recorded
+ * `{ok:false, unavailable}` for a source that is available at `?icpId=`. The
+ * round-2 comment said both reads were "honestly available" — true of the
+ * allowlist, false of the call. Reachability was checked; the route's own
+ * CONTRACT was not.
+ *
+ * THE INVARIANT. Every specified source is requested in the form the route
+ * actually accepts, so an `unavailable` record means the source refused a
+ * well-formed request — never that we asked wrong.
+ *
+ * THE POPULATION IS EVERY READ THIS BUNDLE ISSUES, not only the three stats
+ * sources the finding named. The defect class is "the request shape does not
+ * satisfy the handler's own parameter requirements", and nothing about it is
+ * special to stats.json — so all nine reads are stated here, each with the
+ * handler line the requirement was read from. The brief named three; the
+ * property ranges over all of them, and a table that covered three would leave
+ * the next one unwatched.
+ *
+ * THE METHOD that proves the population complete lives in the test
+ * (cli/test/bundle.test.ts): the stub REFUSES exactly as each handler does, and
+ * the run's recorded request set is compared against this table in BOTH
+ * directions — a read with no entry here fails, and an entry never exercised
+ * fails. The population is derived from execution, not from this list.
+ */
+export const READ_CONTRACTS = [
+    {
+        route: 'GET /api/export/[icpId]',
+        requires: 'path icpId; ?purpose= optional (defaults prospecting_activation)',
+        handler: 'export/[icpId]/route.ts:122-125 — params.icpId; purpose defaults when absent',
+    },
+    {
+        route: 'GET /api/contacts/[icpId]',
+        requires: 'path icpId; ?limit= optional',
+        handler: 'contacts/[icpId]/route.ts:13-31 — params.icpId, optional limit',
+    },
+    {
+        route: 'GET /api/contacts/[icpId]/filter-counts',
+        requires: 'path icpId only',
+        handler: 'contacts/[icpId]/filter-counts/route.ts:10-13',
+    },
+    {
+        route: 'GET /api/icps/[id]/sequences',
+        requires: 'path id MUST be a uuid — 400 invalid_icp_id otherwise',
+        handler: 'icps/[id]/sequences/route.ts:154-158 — UUID_RE.test(icpId)',
+    },
+    {
+        route: 'GET /api/icps/[id]/sequences/[seqId]',
+        requires: 'path id AND seqId must BOTH be uuids — 400 invalid_id otherwise',
+        handler: 'icps/[id]/sequences/[seqId]/route.ts:89-92 — UUID_RE on both',
+    },
+    {
+        route: 'GET /api/replies/[icpId]',
+        requires: 'path icpId; every filter optional',
+        handler: 'replies/[icpId]/route.ts:6-38',
+    },
+    {
+        route: 'GET /api/billing/usage',
+        requires: 'REQUIRED ?icpId= — 404 without it',
+        handler: 'billing/usage/route.ts:36-37 — searchParams.get(\'icpId\'), 404 when absent',
+    },
+    {
+        route: 'GET /api/pipeline/[icpId]',
+        requires: 'path icpId only',
+        handler: 'pipeline/[icpId]/route.ts:8-19',
+    },
+    {
+        route: 'GET /api/agent/lists/[id]/events',
+        requires: 'path id; ?cursor= and ?sequence_id= optional, both validated',
+        handler: 'agent/lists/[id]/events/route.ts:134-144',
+    },
+];
+/**
+ * Page `GET /api/agent/lists/[id]/events` to exhaustion (AC3).
+ *
+ * THE LOOP TERMINATES ON THE SERVER'S OWN `next_cursor`, and it refuses to
+ * accept the same cursor twice. A server that echoed a cursor unchanged — or a
+ * client that forgot to send it — would otherwise re-read page one forever and
+ * write a bundle that looks big and is one page repeated. An unpaged or
+ * silently truncated read destroying data is the failure class §3.4 names by
+ * name, so both directions are refused rather than tolerated.
+ */
+export async function pageEvents(ctx, listId, maxRows, sequenceId) {
+    const rows = [];
+    const seen = new Set();
+    let cursor;
+    for (;;) {
+        const query = {};
+        if (sequenceId !== undefined)
+            query.sequence_id = sequenceId;
+        if (cursor !== undefined)
+            query.cursor = cursor;
+        const body = (await getJson(ctx, `/api/agent/lists/${encodeURIComponent(listId)}/events`, Object.keys(query).length > 0 ? query : undefined));
+        if (!Array.isArray(body.events)) {
+            throw new CliError(EXIT.SERVER, 'error: events read returned no events array', `list ${listId}`);
+        }
+        rows.push(...body.events);
+        if (rows.length > maxRows) {
+            throw new EnvelopeExceeded('events.csv', `more than ${maxRows} rows`);
+        }
+        const next = body.next_cursor;
+        if (next === null || next === undefined)
+            return rows;
+        if (typeof next !== 'string' || next.length === 0 || seen.has(next)) {
+            throw new CliError(EXIT.SERVER, 'error: the events pager was handed a cursor it cannot advance on', `list ${listId}`);
+        }
+        seen.add(next);
+        cursor = next;
+    }
+}
+// ── CSV construction ────────────────────────────────────────────────────────
+function pick(row, keys) {
+    return keys.map((key) => row[key] ?? null);
+}
+/** contacts.csv rows, from `GET /api/contacts/[icpId]`'s camelCase shape. */
+export function contactRows(contacts) {
+    return contacts.map((c) => [
+        c.contactId ?? null,
+        c.name ?? null,
+        c.title ?? null,
+        c.email ?? null,
+        c.zerobounceStatus ?? null,
+        c.linkedinUrl ?? null,
+        c.phone ?? null,
+        c.companyName ?? null,
+        c.companyDomain ?? null,
+        c.tier ?? null,
+    ]);
+}
+/** events.csv rows, actor flattened into its two fields. */
+export function eventRows(events) {
+    return events.map((e) => {
+        const actor = (e.actor ?? null);
+        return [
+            ...pick(e, ['contact_id', 'kind', 'channel', 'sequence_step', 'sent_at']),
+            actor?.type ?? null,
+            actor?.id ?? null,
+        ];
+    });
+}
+/**
+ * How many cells in these rows the probe calls hazardous (AC7's manifest count).
+ *
+ * It runs the SAME probe the serializer runs, over the same final values, so
+ * the number is "cells this bundle neutralized" and not an estimate of it. It
+ * counts CELLS, not rows: one row with two hazardous fields is two.
+ *
+ * "THE SAME FINAL VALUES" MEANS AFTER `toCsvValue`, and the first version of
+ * this skipped non-strings, which broke that claim. `serializeCsvCell` stringifies
+ * and THEN probes, so a numeric cell is neutralized on its stringified form: a
+ * negative number is written `"'-5"` while a raw-cell counter reported zero. The
+ * count and the bytes have to be computed from the same value or the manifest
+ * is describing a different document than the one on disk. Same class as the CRM
+ * path's `str()` coercion — found by sweeping this diff for it.
+ */
+export function countHazards(rows) {
+    let count = 0;
+    for (const row of rows) {
+        for (const cell of row) {
+            if (isFormulaHazard(toCsvValue(cell)))
+                count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * The first sequence id in a `GET /api/icps/[id]/sequences` response, or null.
+ *
+ * Tolerant of both shapes the route could answer with — a bare array or an
+ * object wrapping one — because the bundle should not fail to write six good
+ * files over the shape of the seventh. It never GUESSES an id: anything it
+ * cannot read an id out of is null, which the manifest then records.
+ */
+export function firstSequenceId(body) {
+    const list = Array.isArray(body)
+        ? body
+        : Array.isArray(body?.sequences)
+            ? (body.sequences)
+            : [];
+    for (const row of list) {
+        const id = row?.id;
+        if (typeof id === 'string' && id.length > 0)
+            return id;
+    }
+    return null;
+}
+/** The staging directory's name prefix, and the displaced bundle's. */
+const STAGING_PREFIX = '.predictable-bundle-';
+const DISPLACED_INFIX = '.replaced-';
+/**
+ * Put back a previous bundle that a KILLED process left displaced (r3 item
+ * R2-9, P2).
+ *
+ * ── WHAT IS AND IS NOT CURED, STATED PLAINLY ───────────────────────────────
+ *
+ * The install is two renames: the old bundle moves aside, then staging moves
+ * into its place. Between them the destination does not exist. Round 2 cured
+ * every CATCHABLE failure in that gap — EXDEV is gone because staging is a
+ * sibling, and the catch restores the displaced directory — but a SIGKILL runs
+ * no catch, and the invariant the finding states is stronger: NO OPERATION
+ * AFTER THE DESTINATION DISAPPEARS MAY FAIL.
+ *
+ * THAT INVARIANT IS NOT REACHABLE WITH NODE'S PORTABLE PRIMITIVES, and saying
+ * so is more useful than a cure that looks like one. Replacing a non-empty
+ * directory in ONE atomic act needs an exchange primitive Node does not expose:
+ * Linux's `renameat2(RENAME_EXCHANGE)` or macOS's deprecated,
+ * filesystem-specific `exchangedata`. `renameSync` over an existing non-empty
+ * directory fails with ENOTEMPTY, so the aside-then-install order is forced.
+ * The alternative — making `--out` a SYMLINK to a versioned directory, which
+ * IS atomically replaceable — changes what a customer finds on disk and is a
+ * product decision, not a bug fix. It is named in the delivery report.
+ *
+ * SO THE WINDOW IS CLOSED FOR DATA LOSS RATHER THAN FOR EXISTENCE. A process
+ * killed inside it leaves the previous bundle intact under a sibling name, and
+ * this puts it back. The user-visible failure becomes "the bundle is one run
+ * old" instead of "the bundle is gone and its bytes are under a dotted name
+ * nobody will look for".
+ *
+ * IT PUTS IT BACK ON THE NEXT RUN THAT REACHES THE WRITE, NOT ON THE NEXT RUN.
+ * Its only call site is the first act of the write phase, and the write phase
+ * begins only after every remote read has succeeded. A following run that
+ * fails a read — a 500, an offline host — throws before recovery is reached
+ * and leaves the destination absent for another round. Nothing is lost on that
+ * path either, but the restore is owed to the next CLEAN run, and prose that
+ * says "the next run" claims more than the call site delivers.
+ *
+ * IT RESTORES ONLY WHEN THERE IS NO AMBIGUITY: the destination must be absent
+ * (a present destination means the install completed and the leftover is
+ * garbage from a later crash) and there must be EXACTLY ONE leftover. Two
+ * leftovers mean two crashes, and choosing between them would be a guess about
+ * which bundle a user wants. It never deletes: a leftover it cannot place is
+ * left where a human can find it.
+ */
+export function recoverDisplacedBundle(outDir) {
+    if (existsSync(outDir))
+        return null;
+    const parent = join(outDir, '..');
+    if (!existsSync(parent))
+        return null;
+    const siblings = readdirSync(parent);
+    // A DEFECT IN THIS RECOVERY, FOUND BY ASKING WHAT ELSE MAKES THE DESTINATION
+    // ABSENT. A crash is not the only answer: ANOTHER RUN currently between its
+    // two moves has exactly the same signature — destination gone, one leftover
+    // beside it — and "recovering" that would hand a second process the first
+    // one's bundle and make its install fail ENOTEMPTY.
+    //
+    // A live run always holds its staging directory from mkdtemp until the
+    // install, which spans precisely the window where the destination is absent.
+    // So a staging sibling means a run is in flight and recovery stands down.
+    // It is not a lock and it is not claimed as one — two runs against the same
+    // --out were already undefined. It closes the window this function opened.
+    if (siblings.some((entry) => entry.startsWith(STAGING_PREFIX)))
+        return null;
+    const prefix = `${basename(outDir)}${DISPLACED_INFIX}`;
+    const leftovers = siblings.filter((entry) => entry.startsWith(prefix)).sort();
+    if (leftovers.length !== 1)
+        return null;
+    renameSync(join(parent, leftovers[0]), outDir);
+    return leftovers[0];
+}
+/**
+ * THE CAMPAIGN-BUNDLE VERB CORE — every read, every serialization, the whole
+ * envelope, and the manifest. Shared by BOTH heads (spec §3.4, ticket T10-AC5).
+ *
+ * WHY IT IS SEPARATE FROM `writeCampaignBundle`. §3.4 gives the two heads
+ * different SINKS and the same bundle: "CLI writes them to disk; the MCP head
+ * returns them as sized tool results". Everything above the sink — the six
+ * reads, the pagination, the completeness accounting, the header grammar, the
+ * row cap, the byte cap and `bundle_envelope_exceeded` — is one body of code
+ * called by both, because T10-AC5 requires a shared verb core rather than a
+ * second implementation that agrees today and drifts next month.
+ *
+ * NOTHING TOUCHES THE FILESYSTEM HERE, and that is load-bearing rather than
+ * incidental: every byte is computed and every cap checked BEFORE the caller's
+ * sink runs, which is exactly what lets `writeCampaignBundle` promise that a
+ * breach leaves the destination as it was, and lets the MCP head refuse an
+ * over-cap bundle without having produced a partial one.
+ *
+ * THE TRANSPORT IS THE CALLER'S. `ctx.transport` (see `RequestContext`) is how
+ * the hosted head reaches the same six routes in-process while the CLI reaches
+ * them over HTTP. The reads, their order, their query shapes and their
+ * refusals are identical either way — which is the property AC5 asserts by
+ * pointing both heads' tests at the same fixtures.
+ */
+export async function assembleCampaignBundle(input) {
+    const { ctx, listId, purpose, env } = input;
+    const { maxRows, maxBytes } = envelopeCaps(env);
+    const id = encodeURIComponent(listId);
+    // ── accounts.csv: verbatim bytes, plus its headers ────────────────────────
+    const accountsCall = { method: 'GET', path: `/api/export/${id}`, query: { purpose } };
+    const accountsRes = await send(ctx, accountsCall);
+    const accountsFailure = classify(accountsRes, accountsCall);
+    if (accountsFailure)
+        throw accountsFailure;
+    const exportHeaders = {};
+    for (const key of EXPORT_HEADER_KEYS)
+        exportHeaders[key] = accountsRes.headers.get(key);
+    // ── the JSON reads ────────────────────────────────────────────────────────
+    const contacts = (await getJson(ctx, `/api/contacts/${id}`));
+    if (!Array.isArray(contacts)) {
+        throw new CliError(EXIT.SERVER, 'error: contacts read did not return an array', `list ${listId}`);
+    }
+    const filterCounts = (await getJson(ctx, `/api/contacts/${id}/filter-counts`));
+    // TWO DIFFERENT READS, and §3.4 names both. `stats.json` is the sequences
+    // LIST (the per-sequence stats the list read carries); `sequence.json` is ONE
+    // sequence's DETAIL. Pointing both at the list read would write the same
+    // bytes twice and quietly drop the detail the bundle promises.
+    const sequenceList = await getJson(ctx, `/api/icps/${id}/sequences`);
+    const selectedSequenceId = input.sequenceId ?? firstSequenceId(sequenceList);
+    // NULL IS AN ANSWER, NOT A FAILURE. A list with no sequences has no detail to
+    // write; the file is `null` and the manifest says which sequence it is (or
+    // that there is none), so a reader can tell "no sequence" from "the wrong one".
+    const sequenceDetail = selectedSequenceId === null
+        ? null
+        : await getJson(ctx, `/api/icps/${id}/sequences/${encodeURIComponent(selectedSequenceId)}`);
+    const replies = await getJson(ctx, `/api/replies/${id}`);
+    // stats.json IS THREE READS, NOT ONE (§3.4, r2 finding 2). Round 1 wrote the
+    // sequences list alone. The spec's source column names three, verbatim:
+    //   GET /api/icps/[id]/sequences (list-stats) + GET /api/billing/usage
+    //   + GET /api/pipeline/[icpId]
+    // Both of the missing two are live in the generated allowlist (stats.usage,
+    // stats.pipeline, pending:false) and T6b — the slice that gated the anchored
+    // billing/usage read — is in LANDED_SLICES, so they are honestly available.
+    // ANCHORED, BECAUSE THE ROUTE REQUIRES IT (r3 R2-1). `/api/billing/usage`
+    // is CLIENT-scoped and resolves its client FROM an ICP: §10i's "anchor both"
+    // ruling means `?icpId=` is mandatory on every channel, and the handler
+    // returns 404 without it. An unanchored call is not a source that refused —
+    // it is a malformed request recording itself as unavailability. See
+    // READ_CONTRACTS above for every read's requirement and where it was read.
+    const usage = await readStatsSource(ctx, `/api/billing/usage`, { icpId: listId });
+    const pipeline = await readStatsSource(ctx, `/api/pipeline/${id}`);
+    const events = await pageEvents(ctx, listId, maxRows, input.sequenceId);
+    // ── serialize ─────────────────────────────────────────────────────────────
+    const contactData = contactRows(contacts);
+    const eventData = eventRows(events);
+    // ── THE COMPLETENESS ACCOUNTING, ONE ADDRESS (r2 findings 5 and 6) ───────
+    //
+    // Round 1 applied the row cap to contacts and events, and counted hazards in
+    // contacts and events. accounts.csv was in neither, so a bundle of 250,001
+    // accounts under 100 MB succeeded, and hazardous company names were correctly
+    // neutralized in the file while the manifest reported zero of them.
+    //
+    // THE FIX IS NOT "ADD accounts.csv TO BOTH LISTS". That is the spelling, and
+    // it leaves the next file added to the bundle in the same hole. This table
+    // ranges over ALL of BUNDLE_FILES and is the single source for the row cap,
+    // the manifest's row map and the manifest's hazard map. A file added to
+    // BUNDLE_FILES without an entry here fails to typecheck.
+    //
+    // AND THE EXCLUSIONS ARE STATED, NOT IMPLIED. A JSON document has no rows and
+    // is not a spreadsheet cell, so it is genuinely outside both claims — but a
+    // reader of manifest.json must be able to see that it was excluded ON PURPOSE
+    // and why, rather than infer it from a number that quietly does not cover it.
+    const BYTES_SELF_REFERENTIAL = 'This map lives inside manifest.json, so manifest.json\'s own byte length depends on the digits written here — a self-reference with no fixed point. Its size is reported by the envelope total and by the CLI result, both measured after the file exists.';
+    const NO_ROWS = 'JSON document — it has no row set, so no row count exists. Inside the byte envelope, outside the row cap.';
+    const NOT_A_SPREADSHEET = 'JSON document — a formula-looking string in JSON is not a spreadsheet cell, so the CSV hazard probe does not range over it.';
+    // accounts.csv's numbers come from the SERVER, which is the only party that
+    // still had the values: this bundle holds accounts.csv as verbatim bytes and
+    // never parses it. Missing or malformed is a REFUSAL, not a skip — the row cap
+    // is a safety claim, and a cap that silently stops applying to a file is the
+    // same defect as never having covered it.
+    //
+    // ── THE GRAMMAR, AND WHY `Number()` WAS NOT ONE (r3 item R2-2) ─────────────
+    //
+    // Round 2 accepted any finite `Number(raw)`. That admits `-1`, `1.5`, `0x10`,
+    // `1e6`, `  7  ` and `Infinity`'s neighbours — and because the client
+    // deliberately never parses accounts.csv, nothing downstream contradicts them.
+    // `X-Export-Eligible-Count: -1` walks a 250,001-row file straight past
+    // `rows > maxRows`; `X-Export-Formula-Hazard-Count: -5` subtracts five from
+    // the manifest's total. A cap defeated by a minus sign is not a cap.
+    //
+    // THE INVARIANT: a number the bundle's safety claims rest on is a NON-NEGATIVE
+    // DECIMAL INTEGER, written in the shortest form of itself, or the bundle
+    // refuses. `String(n) === raw` is the whole grammar: it rejects signs,
+    // fractions, exponents, radix prefixes, padding and surrounding whitespace in
+    // one comparison, and it cannot drift from the value actually used because the
+    // value is what generates the comparison.
+    const HEADER_NUMBER = /^(0|[1-9][0-9]*)$/;
+    const accountsCount = (key) => {
+        const raw = exportHeaders[key] ?? null;
+        if (raw === null || !HEADER_NUMBER.test(raw)) {
+            throw new CliError(EXIT.SERVER, 'error: accounts.csv cannot be accounted for', `${key} is ${raw === null ? 'absent' : JSON.stringify(raw)}, not a non-negative decimal integer; ` +
+                'the bundle will not claim a row cap or a hazard count it cannot compute. ' +
+                'THE LIKELY CAUSE IS A DEPLOY SKEW: this CLI is newer than the dashboard it is ' +
+                'talking to, and that dashboard does not send this header yet. THE REMEDY IS TO ' +
+                'DEPLOY THE DASHBOARD (or point PREDICTABLE_BASE_URL at one already carrying ' +
+                'T8). Refusing is deliberate: an under-reported count would let a truncated or ' +
+                'unneutralized accounts.csv ship inside a bundle that claims otherwise.');
+        }
+        return Number(raw);
+    };
+    // EVERY HEADER-SOURCED NUMBER, NOT ONLY THE TWO THE FINDING NAMED. The
+    // population is `EXPORT_HEADER_KEYS` minus the one non-numeric key, derived
+    // from that list rather than re-typed, so a header added to the bundle cannot
+    // be added outside the grammar. The four exclusion counts are not inputs to a
+    // cap — but they ARE the manifest's claim about what the server filtered out,
+    // and a claim of `-3 organizations excluded` is corrupt whether or not
+    // anything divides by it.
+    //
+    // AND THAT IS THE WHOLE POPULATION IN THIS CLI, not just in this file:
+    // `headers.get` appears in exactly one other place, `http.ts:146`, where
+    // `retry-after` is interpolated into an error MESSAGE as a string. It is
+    // never parsed to a number and no claim rests on it, so it is outside this
+    // rule — measured, not assumed by locality.
+    const NON_NUMERIC_HEADERS = new Set(['x-export-purpose']);
+    for (const key of EXPORT_HEADER_KEYS) {
+        if (!NON_NUMERIC_HEADERS.has(key))
+            accountsCount(key);
+    }
+    // AND THE HAZARD COUNT IS BOUNDED BY THE CELLS THAT COULD CARRY ONE. A
+    // well-formed integer is still a lie if it is larger than the file can hold,
+    // and this number is added into the manifest's total, so an inflated header
+    // inflates a claim about every other file too.
+    //
+    // THE BOUND COSTS NO PARSE, which matters because never parsing accounts.csv
+    // is a standing invariant here (bundle.ts:26-31). A hazardous cell holds at
+    // least one byte, and every cell after the first is preceded by at least one
+    // delimiter byte, so a file of B bytes cannot hold more than (B + 1) / 2
+    // hazardous cells. It is a ceiling, not an estimate: it is satisfied by any
+    // honest count and violated only by one the file could not have produced.
+    const accountsBytes = Buffer.byteLength(accountsRes.text, 'utf8');
+    const maxAccountsHazards = Math.floor((accountsBytes + 1) / 2);
+    const declaredHazards = accountsCount('x-export-formula-hazard-count');
+    if (declaredHazards > maxAccountsHazards) {
+        throw new CliError(EXIT.SERVER, 'error: accounts.csv cannot be accounted for', `x-export-formula-hazard-count is ${declaredHazards}, but accounts.csv is ${accountsBytes} bytes ` +
+            `and cannot hold more than ${maxAccountsHazards} hazardous cells; the bundle will not carry a ` +
+            'count the file it describes could not have produced');
+    }
+    const accounting = {
+        'accounts.csv': { rows: accountsCount('x-export-eligible-count'), hazards: accountsCount('x-export-formula-hazard-count') },
+        'contacts.csv': { rows: contactData.length, hazards: countHazards(contactData) },
+        'events.csv': { rows: eventData.length, hazards: countHazards(eventData) },
+        'sequence.json': { rows: null, rowsWhy: NO_ROWS, hazards: null, hazardsWhy: NOT_A_SPREADSHEET },
+        'replies.json': { rows: null, rowsWhy: NO_ROWS, hazards: null, hazardsWhy: NOT_A_SPREADSHEET },
+        'stats.json': { rows: null, rowsWhy: NO_ROWS, hazards: null, hazardsWhy: NOT_A_SPREADSHEET },
+        'manifest.json': { rows: null, rowsWhy: NO_ROWS, hazards: null, hazardsWhy: NOT_A_SPREADSHEET },
+    };
+    // The cap ranges over every file that HAS a row count — derived from the
+    // table above, never from a second hand-written list of file names.
+    for (const file of BUNDLE_FILES) {
+        const rows = accounting[file].rows;
+        if (rows !== null && rows > maxRows) {
+            throw new EnvelopeExceeded(file, `${rows} rows exceeds ${maxRows}`);
+        }
+    }
+    const bodies = {
+        'accounts.csv': accountsRes.text,
+        'contacts.csv': serializeCsvRows([CONTACT_COLUMNS, ...contactData]),
+        'events.csv': serializeCsvRows([EVENT_COLUMNS, ...eventData]),
+        'sequence.json': `${JSON.stringify(sequenceDetail, null, 2)}\n`,
+        'replies.json': `${JSON.stringify(replies, null, 2)}\n`,
+        'stats.json': `${JSON.stringify({
+            sequences: { ok: true, data: sequenceList },
+            usage,
+            pipeline,
+        }, null, 2)}\n`,
+    };
+    // CONTACTS EQUALITY (AC2). `filter-counts.all` is the server's own total for
+    // this list, computed by a different query than the table read. Asserting
+    // they agree is what makes "the bundle is complete" a claim rather than a
+    // hope — a truncated contacts read is silent otherwise, and §3.4 names
+    // silent truncation as a known failure class.
+    //
+    // AND IT FAILS CLOSED (r2 finding 9). Round 1 read
+    // `typeof expectedContacts === 'number' && expectedContacts !== …`, so an
+    // absent `all`, a string "1200", or any other schema drift SKIPPED the check
+    // entirely and a truncated 1000-row read was written as a complete bundle.
+    // That is a guard whose own enabling condition comes from the data it is
+    // guarding: the input that breaks the data also turns the guard off. An
+    // expected total that is missing or unusable is a REFUSAL, never a skip.
+    const expectedContacts = filterCounts.all;
+    if (typeof expectedContacts !== 'number' || !Number.isFinite(expectedContacts)) {
+        throw new CliError(EXIT.SERVER, 'error: contacts.csv completeness cannot be proven', `the list's filter-counts total is ${JSON.stringify(expectedContacts) ?? 'undefined'}, not a number; the bundle will not claim a completeness it cannot check`);
+    }
+    if (expectedContacts !== contactData.length) {
+        throw new CliError(EXIT.SERVER, 'error: contacts.csv is incomplete', `contacts.csv has ${contactData.length} rows, the list's filter-counts total is ${expectedContacts}`);
+    }
+    const manifest = {
+        schema: 'predictable.campaign-bundle/1',
+        list_id: listId,
+        generated_at: input.now,
+        // The purpose is recorded because `reporting_history` is a DELIBERATE
+        // suppression bypass (AC5, §6): the file has to say so, or a bundle that
+        // skipped the suppression filter is indistinguishable from one that did not.
+        purpose,
+        sequence_id: selectedSequenceId,
+        /** Set when --sequence narrowed events.csv; null when it holds every event. */
+        events_filtered_by_sequence: input.sequenceId ?? null,
+        export_headers: exportHeaders,
+        // EVERY EMITTED FILE IS IN THE FILES MAP, and the one that cannot carry a
+        // number says so (r3 item R2-3, Class A). Round 2 FILTERED manifest.json
+        // out: the bundle emitted seven files and the map listed six, with nothing
+        // in the artifact saying which of "excluded on purpose" and "forgotten" a
+        // consumer was looking at. Rows and hazards already answered that question
+        // through `completeness_scope`; bytes did not, and inventing a second
+        // mechanism for the third claim is how the next one goes missing too.
+        //
+        // WHY THE VALUE IS null RATHER THAN A NUMBER. This map is INSIDE
+        // manifest.json, so manifest.json's own byte length depends on the digits
+        // written here — a self-reference with no fixed point. `null` plus a stated
+        // reason is the honest form; a number would be wrong the moment it was
+        // written. The bundle's OTHER byte claims do cover it: the envelope total
+        // below sums all seven, and `BundleResult.files` reports all seven measured
+        // after the manifest exists.
+        files: Object.fromEntries(BUNDLE_FILES.map((f) => [
+            f,
+            f === 'manifest.json' ? null : Buffer.byteLength(bodies[f] ?? '', 'utf8'),
+        ])),
+        // EVERY BUNDLE FILE APPEARS IN EVERY CLAIM, or the claim says why not.
+        // Both maps below range over ALL of BUNDLE_FILES from the accounting table,
+        // so no file can be silently outside a number the manifest reports.
+        rows: Object.fromEntries(BUNDLE_FILES.map((f) => [f, accounting[f].rows])),
+        contacts_filter_counts: filterCounts,
+        // The TOTAL stays a number, which is the shape AC7 names — it now includes
+        // accounts.csv, whose count comes from the producing route's own header.
+        formula_hazard: BUNDLE_FILES.reduce((sum, f) => sum + (accounting[f].hazards ?? 0), 0),
+        formula_hazard_by_file: Object.fromEntries(BUNDLE_FILES.map((f) => [f, accounting[f].hazards])),
+        // THE SCOPE OF THOSE TWO NUMBERS, IN THE ARTIFACT. A count that quietly
+        // does not cover a file is a lie by omission; a count that names what it
+        // does not cover, and why, is a measurement.
+        completeness_scope: {
+            rows_excluded: Object.fromEntries(BUNDLE_FILES.filter((f) => accounting[f].rowsWhy).map((f) => [f, accounting[f].rowsWhy])),
+            formula_hazard_excluded: Object.fromEntries(BUNDLE_FILES.filter((f) => accounting[f].hazardsWhy).map((f) => [f, accounting[f].hazardsWhy])),
+            bytes_excluded: {
+                'manifest.json': BYTES_SELF_REFERENTIAL,
+            },
+        },
+        // WHICH SOURCES stats.json actually carries (r2 finding 2). A source that
+        // was refused is named here as well as in the file, so "the bundle has no
+        // usage data" and "usage was unavailable, for this reason" stay distinct.
+        stats_sources: {
+            sequences: 'ok',
+            usage: usage.ok ? 'ok' : `unavailable: ${usage.unavailable}`,
+            pipeline: pipeline.ok ? 'ok' : `unavailable: ${pipeline.unavailable}`,
+        },
+        envelope: { max_rows: maxRows, max_bytes: maxBytes },
+    };
+    bodies['manifest.json'] = `${JSON.stringify(manifest, null, 2)}\n`;
+    const total = BUNDLE_FILES.reduce((sum, f) => sum + Buffer.byteLength(bodies[f] ?? '', 'utf8'), 0);
+    if (total > maxBytes) {
+        // NAMED BY THE LARGEST FILE, because "the bundle is too big" tells an
+        // operator nothing they can act on.
+        const largest = [...BUNDLE_FILES].sort((a, b) => Buffer.byteLength(bodies[b] ?? '', 'utf8') - Buffer.byteLength(bodies[a] ?? '', 'utf8'))[0];
+        throw new EnvelopeExceeded(largest, `bundle is ${total} bytes, over the ${maxBytes}-byte cap`);
+    }
+    return {
+        bodies,
+        manifest,
+        files: Object.fromEntries(BUNDLE_FILES.map((f) => [f, Buffer.byteLength(bodies[f] ?? '', 'utf8')])),
+    };
+}
+/**
+ * `export campaign` as the CLI serves it: the shared core above, then the disk
+ * install. The core produces the bytes; this function is only the sink.
+ */
+export async function writeCampaignBundle(input) {
+    const { outDir } = input;
+    const { bodies, manifest, files } = await assembleCampaignBundle(input);
+    // ── NO PARTIAL BUNDLE ON DISK (AC4) ──────────────────────────────────────
+    //
+    // Every byte is computed and every cap checked BEFORE anything is written,
+    // and even then the files land in a staging directory that is renamed into
+    // place as the last act. A breach therefore leaves the destination exactly as
+    // it was — nonexistent, or the previous bundle, untouched. Writing as we go
+    // and deleting on failure would leave a half-bundle behind for any failure
+    // between the write and the delete.
+    // STAGING LIVES BESIDE THE DESTINATION, NOT IN THE OS TEMP DIR (r2 finding
+    // 10). It used to stage under tmpdir(), and when /tmp and the output path are
+    // on different filesystems renameSync throws EXDEV — AFTER rmSync has already
+    // deleted the previous bundle and BEFORE any new one exists. The comment above
+    // promises the destination is left exactly as it was, and on that path it was
+    // destroyed. A same-filesystem rename cannot fail that way.
+    //
+    // The old bundle is also moved ASIDE rather than deleted, and removed only
+    // once the new one is in place, so the destroying operation is the LAST one
+    // and nothing can fail after it.
+    const write = input.writeFile ?? ((path, contents) => writeFileSync(path, contents, 'utf8'));
+    const parent = join(outDir, '..');
+    mkdirSync(parent, { recursive: true });
+    recoverDisplacedBundle(outDir);
+    const rename = input.rename ?? renameSync;
+    const staging = mkdtempSync(join(parent, STAGING_PREFIX));
+    const displaced = `${outDir}${DISPLACED_INFIX}${basename(staging).slice(STAGING_PREFIX.length)}`;
+    let moved = false;
+    try {
+        for (const file of BUNDLE_FILES)
+            write(join(staging, file), bodies[file] ?? '');
+        if (existsSync(outDir)) {
+            rename(outDir, displaced);
+            moved = true;
+        }
+        rename(staging, outDir);
+    }
+    catch (err) {
+        rmSync(staging, { recursive: true, force: true });
+        // Put the previous bundle back before surfacing the failure: a breach must
+        // leave the destination exactly as it was.
+        if (moved && !existsSync(outDir))
+            renameSync(displaced, outDir);
+        else if (moved)
+            rmSync(displaced, { recursive: true, force: true });
+        throw err;
+    }
+    if (moved)
+        rmSync(displaced, { recursive: true, force: true });
+    return { directory: outDir, files, manifest };
+}
+//# sourceMappingURL=bundle.js.map