@adcp/sdk 15.9.0 → 15.9.1

package/dist/lib/reporting/bigquery/index.d.mts

@@ -11,11 +11,16 @@ import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, R
  * are the adopter's.
  *
  * Exactly-once loading: a batch (change-feed range, revision list, job IDs) is
- * planned durably in PostgreSQL before any load. A crash between the load and
- * the cursor commit replays the same batch under the same job IDs, which
- * BigQuery refuses to run twice. A failed load job is retried under a new
- * attempt suffix only after BigQuery reports that job finished with an error,
- * and each table keeps its own attempt count, so no batch lands twice.
+ * planned durably in PostgreSQL before any load. Before every submission the
+ * sink looks the deterministic job ID up in the destination project and
+ * location: a job that finished cleanly counts as loaded, a job still running
+ * is waited for (never uploaded again), and only a missing job is uploaded.
+ * A crash or timeout between the load and the cursor commit therefore replays
+ * the same batch under the same job IDs without a second upload. A failed load
+ * job is retried under a new attempt suffix only after BigQuery reports that
+ * job finished with an error, and each table keeps its own attempt count, so
+ * no batch lands twice. A load that outlasts the deadline never changes the job
+ * ID: the sink grows that table's deadline instead (persisted with the plan).
  * Concurrent runs claim one durable plan with compare-and-swap. Replays of
  * that plan share job IDs; stale runs cannot change its attempts or cursor.
  */
@@ -36,7 +41,7 @@ export interface ReportingBigQueryClientV1 {
         location?: string;
     }): {
         getMetadata(): Promise<unknown>;
-        /** Request cancellation. Optional so wrappers written before the sink used it still type-check. */
+        /** @deprecated Unused: BigQuery does not stop a running load, so the sink never cancels. Kept so wrappers that declare it still type-check. */
         cancel?(): Promise<unknown>;
     };
     query(options: {
@@ -74,7 +79,11 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     datasetId: string;
     rowsTableId: string;
     revisionsTableId: string;
-    /** Dataset location, so jobs run in the dataset's region. */
+    /**
+     * Dataset location, so jobs run in the dataset's region. Set it for any dataset outside the US and EU
+     * multi-regions: BigQuery answers a job lookup without the right location with 404, and the sink then
+     * cannot find the jobs it created.
+     */
     location?: string;
     /** Restrict the sink to one account; omit for the deployment-wide feed. */
     account_id?: string;
@@ -98,18 +107,24 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
      */
     labels?: Readonly<Record<string, string>>;
     /**
-     * Deadline for one load (and for each status check). Default 10 minutes.
-     * When a load exceeds it, the sink asks BigQuery to cancel that job by its
-     * deterministic ID (in `projectId` and `location`) and rejects, leaving the
-     * plan in place. The next run finds the cancelled job finished with an
-     * error, advances that table's attempt and rejects; the run after that
-     * loads under the new attempt. If the cancel has not taken effect yet the
-     * next run waits for the job. Each attempt doubles the load deadline (up to
-     * 6 hours), so a load that is slow but healthy converges; set this above
-     * your slowest expected load to avoid the cancelled attempts. A status
-     * check that times out is not cancelled. This is a client-side deadline:
-     * BigQuery's server-side `jobTimeoutMs` cannot be set on a local-file load
-     * through the official client, and cancellation is best effort.
+     * Base deadline for one run's work on one load. Default 10 minutes. It bounds
+     * how long a run uploads a file or waits for a running job; it does not bound
+     * the job. BigQuery does not stop a load when the client gives up (a cancel
+     * is accepted and the job finishes anyway), so the sink never cancels.
+     * Before every submission it looks the deterministic job ID up in `projectId`
+     * and `location`: a job that finished cleanly is accepted, a job that is
+     * pending or running is waited for (polled within the deadline) instead of
+     * being uploaded again, and only a missing job is uploaded. When the
+     * deadline passes, the run rejects with the plan retained and nothing
+     * advanced, and the next run checks the job again. Each such timeout doubles
+     * that table's deadline for later runs (up to 6 hours, persisted with the
+     * plan, and never changing the job ID), so an upload slower than the
+     * deadline eventually gets enough time. Set it above your slowest expected
+     * load to avoid the extra runs. Only a job that finished with an error
+     * advances the attempt. A status check that times out is bounded by this base
+     * deadline and does not grow it. This is a client-side deadline: BigQuery's
+     * server-side `jobTimeoutMs` cannot be set on a local-file load through the
+     * official client.
      */
     loadTimeoutMilliseconds?: number;
 }
@@ -153,7 +168,8 @@ export interface BigQueryReportingWarehouseSinkV1 {
      * the destination tables first, or use a new sink name against new tables.
      * Each reset starts a new job ID generation, so reloaded batches submit
      * fresh BigQuery jobs instead of matching the finished jobs of the earlier
-     * history. Nothing holds change retention between `reset()` and the first
+     * history. The sink never cancels a load, so stop every worker and let its
+     * in-flight uploads and jobs finish before emptying the destination tables. Nothing holds change retention between `reset()` and the first
      * committed batch. If `reset()` rejects after clearing the sink's state
      * (the consumer could not be unregistered), call it again before restarting
      * workers; it is idempotent. Needs a store with `removeFeedConsumer`.
@@ -170,6 +186,11 @@ export interface BigQueryReportingWarehouseSinkV1 {
     readonly currentRowsViewSql: string;
 }
 export declare function createBigQueryReportingWarehouseSinkV1(options: CreateBigQueryReportingWarehouseSinkOptionsV1): BigQueryReportingWarehouseSinkV1;
+/**
+ * How long one run may upload a file or wait for a running job: the configured
+ * base doubled once per earlier timeout of that table's load, capped at 6 hours.
+ */
+export declare function reportingWarehouseLoadDeadlineV1(baseMilliseconds: number, timeouts: number): number;
 /** Deterministic load job ID for one planned change-feed range. */
 export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string, generation?: number): string;
 interface WarehouseTablesV1 {

package/dist/lib/reporting/bigquery/index.d.ts

@@ -11,11 +11,16 @@ import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, R
  * are the adopter's.
  *
  * Exactly-once loading: a batch (change-feed range, revision list, job IDs) is
- * planned durably in PostgreSQL before any load. A crash between the load and
- * the cursor commit replays the same batch under the same job IDs, which
- * BigQuery refuses to run twice. A failed load job is retried under a new
- * attempt suffix only after BigQuery reports that job finished with an error,
- * and each table keeps its own attempt count, so no batch lands twice.
+ * planned durably in PostgreSQL before any load. Before every submission the
+ * sink looks the deterministic job ID up in the destination project and
+ * location: a job that finished cleanly counts as loaded, a job still running
+ * is waited for (never uploaded again), and only a missing job is uploaded.
+ * A crash or timeout between the load and the cursor commit therefore replays
+ * the same batch under the same job IDs without a second upload. A failed load
+ * job is retried under a new attempt suffix only after BigQuery reports that
+ * job finished with an error, and each table keeps its own attempt count, so
+ * no batch lands twice. A load that outlasts the deadline never changes the job
+ * ID: the sink grows that table's deadline instead (persisted with the plan).
  * Concurrent runs claim one durable plan with compare-and-swap. Replays of
  * that plan share job IDs; stale runs cannot change its attempts or cursor.
  */
@@ -36,7 +41,7 @@ export interface ReportingBigQueryClientV1 {
         location?: string;
     }): {
         getMetadata(): Promise<unknown>;
-        /** Request cancellation. Optional so wrappers written before the sink used it still type-check. */
+        /** @deprecated Unused: BigQuery does not stop a running load, so the sink never cancels. Kept so wrappers that declare it still type-check. */
         cancel?(): Promise<unknown>;
     };
     query(options: {
@@ -74,7 +79,11 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     datasetId: string;
     rowsTableId: string;
     revisionsTableId: string;
-    /** Dataset location, so jobs run in the dataset's region. */
+    /**
+     * Dataset location, so jobs run in the dataset's region. Set it for any dataset outside the US and EU
+     * multi-regions: BigQuery answers a job lookup without the right location with 404, and the sink then
+     * cannot find the jobs it created.
+     */
     location?: string;
     /** Restrict the sink to one account; omit for the deployment-wide feed. */
     account_id?: string;
@@ -98,18 +107,24 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
      */
     labels?: Readonly<Record<string, string>>;
     /**
-     * Deadline for one load (and for each status check). Default 10 minutes.
-     * When a load exceeds it, the sink asks BigQuery to cancel that job by its
-     * deterministic ID (in `projectId` and `location`) and rejects, leaving the
-     * plan in place. The next run finds the cancelled job finished with an
-     * error, advances that table's attempt and rejects; the run after that
-     * loads under the new attempt. If the cancel has not taken effect yet the
-     * next run waits for the job. Each attempt doubles the load deadline (up to
-     * 6 hours), so a load that is slow but healthy converges; set this above
-     * your slowest expected load to avoid the cancelled attempts. A status
-     * check that times out is not cancelled. This is a client-side deadline:
-     * BigQuery's server-side `jobTimeoutMs` cannot be set on a local-file load
-     * through the official client, and cancellation is best effort.
+     * Base deadline for one run's work on one load. Default 10 minutes. It bounds
+     * how long a run uploads a file or waits for a running job; it does not bound
+     * the job. BigQuery does not stop a load when the client gives up (a cancel
+     * is accepted and the job finishes anyway), so the sink never cancels.
+     * Before every submission it looks the deterministic job ID up in `projectId`
+     * and `location`: a job that finished cleanly is accepted, a job that is
+     * pending or running is waited for (polled within the deadline) instead of
+     * being uploaded again, and only a missing job is uploaded. When the
+     * deadline passes, the run rejects with the plan retained and nothing
+     * advanced, and the next run checks the job again. Each such timeout doubles
+     * that table's deadline for later runs (up to 6 hours, persisted with the
+     * plan, and never changing the job ID), so an upload slower than the
+     * deadline eventually gets enough time. Set it above your slowest expected
+     * load to avoid the extra runs. Only a job that finished with an error
+     * advances the attempt. A status check that times out is bounded by this base
+     * deadline and does not grow it. This is a client-side deadline: BigQuery's
+     * server-side `jobTimeoutMs` cannot be set on a local-file load through the
+     * official client.
      */
     loadTimeoutMilliseconds?: number;
 }
@@ -153,7 +168,8 @@ export interface BigQueryReportingWarehouseSinkV1 {
      * the destination tables first, or use a new sink name against new tables.
      * Each reset starts a new job ID generation, so reloaded batches submit
      * fresh BigQuery jobs instead of matching the finished jobs of the earlier
-     * history. Nothing holds change retention between `reset()` and the first
+     * history. The sink never cancels a load, so stop every worker and let its
+     * in-flight uploads and jobs finish before emptying the destination tables. Nothing holds change retention between `reset()` and the first
      * committed batch. If `reset()` rejects after clearing the sink's state
      * (the consumer could not be unregistered), call it again before restarting
      * workers; it is idempotent. Needs a store with `removeFeedConsumer`.
@@ -170,6 +186,11 @@ export interface BigQueryReportingWarehouseSinkV1 {
     readonly currentRowsViewSql: string;
 }
 export declare function createBigQueryReportingWarehouseSinkV1(options: CreateBigQueryReportingWarehouseSinkOptionsV1): BigQueryReportingWarehouseSinkV1;
+/**
+ * How long one run may upload a file or wait for a running job: the configured
+ * base doubled once per earlier timeout of that table's load, capped at 6 hours.
+ */
+export declare function reportingWarehouseLoadDeadlineV1(baseMilliseconds: number, timeouts: number): number;
 /** Deterministic load job ID for one planned change-feed range. */
 export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string, generation?: number): string;
 interface WarehouseTablesV1 {

package/dist/lib/reporting/bigquery/index.js

@@ -32,7 +32,8 @@ __export(bigquery_exports, {
   createBigQueryReportingWarehouseSinkV1: () => createBigQueryReportingWarehouseSinkV1,
   reportingWarehouseCurrentRowsViewSqlV1: () => reportingWarehouseCurrentRowsViewSqlV1,
   reportingWarehouseDefaultTablesSqlV1: () => reportingWarehouseDefaultTablesSqlV1,
-  reportingWarehouseJobIdV1: () => reportingWarehouseJobIdV1
+  reportingWarehouseJobIdV1: () => reportingWarehouseJobIdV1,
+  reportingWarehouseLoadDeadlineV1: () => reportingWarehouseLoadDeadlineV1
 });
 module.exports = __toCommonJS(bigquery_exports);
 var import_crypto = require("crypto");
@@ -49,14 +50,21 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_warehouse_sinks (
   planned_revisions JSONB,
   planned_rows_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_rows_attempt >= 0),
   planned_revisions_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_revisions_attempt >= 0),
+  planned_rows_timeouts INTEGER NOT NULL DEFAULT 0 CHECK (planned_rows_timeouts >= 0),
+  planned_revisions_timeouts INTEGER NOT NULL DEFAULT 0 CHECK (planned_revisions_timeouts >= 0),
   reset_generation INTEGER NOT NULL DEFAULT 0 CHECK (reset_generation >= 0),
   updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
   CHECK ((planned_to_cursor IS NULL) = (planned_revisions IS NULL))
 );
 ALTER TABLE adcp_reporting_warehouse_sinks
   ADD COLUMN IF NOT EXISTS reset_generation INTEGER NOT NULL DEFAULT 0 CHECK (reset_generation >= 0);
+ALTER TABLE adcp_reporting_warehouse_sinks
+  ADD COLUMN IF NOT EXISTS planned_rows_timeouts INTEGER NOT NULL DEFAULT 0 CHECK (planned_rows_timeouts >= 0);
+ALTER TABLE adcp_reporting_warehouse_sinks
+  ADD COLUMN IF NOT EXISTS planned_revisions_timeouts INTEGER NOT NULL DEFAULT 0 CHECK (planned_revisions_timeouts >= 0);
 `.trim();
 const MAX_LOAD_TIMEOUT = 6 * 36e5;
+const MAX_TIMEOUT_DOUBLINGS = 16;
 let warnedLabelsIgnored = false;
 const PROJECT = /^[a-z][a-z0-9-]{4,61}[a-z0-9]$/;
 const DATASET_OR_TABLE = /^[A-Za-z_][A-Za-z0-9_]{0,1023}$/;
@@ -109,51 +117,104 @@ function createBigQueryReportingWarehouseSinkV1(options) {
     ...options.projectId ? { projectId: options.projectId } : {},
     ...options.location ? { location: options.location } : {}
   } : void 0;
-  async function cancelLoad(jobId, signal) {
+  const uploads = /* @__PURE__ */ new Map();
+  function startUpload(tableId, jobId, lines) {
+    const entry = {
+      startedAt: Date.now(),
+      done: Promise.resolve()
+    };
+    const cleanup = async () => {
+      if (uploads.get(jobId) === entry) uploads.delete(jobId);
+      if (entry.directory) await import_fs.promises.rm(entry.directory, { recursive: true, force: true }).catch(() => {
+      });
+    };
+    entry.done = (async () => {
+      const directory = await import_fs.promises.mkdtemp(path.join((0, import_os.tmpdir)(), "adcp-warehouse-"));
+      entry.directory = directory;
+      const file = path.join(directory, `${jobId}.ndjson`);
+      await import_fs.promises.writeFile(file, lines.length ? lines.join("\n") + "\n" : "", { mode: 384 });
+      return dataset.table(tableId).load(file, {
+        jobId,
+        sourceFormat: "NEWLINE_DELIMITED_JSON",
+        writeDisposition: "WRITE_APPEND",
+        ...options.location ? { location: options.location } : {}
+      });
+    })();
+    const replaced = uploads.get(jobId);
+    uploads.set(jobId, entry);
+    void entry.done.then(cleanup, cleanup);
+    if (replaced?.directory) void import_fs.promises.rm(replaced.directory, { recursive: true, force: true }).catch(() => {
+    });
+    return entry.done;
+  }
+  async function jobStatus(jobId, signal, boundMilliseconds = loadTimeout, context) {
+    let metadata;
     try {
-      const job = options.bigquery.job(jobId, jobOptions);
-      if (typeof job.cancel !== "function") return;
-      const cancel = job.cancel.bind(job);
-      await withinDeadline(cancel, Math.min(loadTimeout, 3e4), signal);
-    } catch (error) {
-      const code = error?.code;
-      if (code === 404 || signal?.aborted) return;
-      process.emitWarning(
-        `Cancelling BigQuery load job ${jobId} failed (${typeof code === "number" || typeof code === "string" ? code : "no status code"}); the job may still be running`,
-        { code: "ADCP_BIGQUERY_SINK_CANCEL_FAILED" }
+      metadata = await withinDeadline(
+        () => options.bigquery.job(jobId, jobOptions).getMetadata(),
+        boundMilliseconds,
+        signal,
+        context
       );
+    } catch (error) {
+      if (error?.code === 404) return "missing";
+      throw error;
     }
+    const record = Array.isArray(metadata) ? metadata[0] : metadata;
+    if (record?.status?.state !== "DONE") return "running";
+    if (record.status.errorResult) {
+      const failure = new Error("A BigQuery load job for this batch failed; it will be retried as a new attempt");
+      Object.defineProperty(failure, "adcpJobFailed", { value: true });
+      throw failure;
+    }
+    return "done";
   }
-  async function loadOnce(tableId, jobId, lines, attempt, signal) {
-    const loadDeadline = Math.min(loadTimeout * 2 ** Math.min(attempt, 16), MAX_LOAD_TIMEOUT);
+  async function loadOnce(role, tableId, jobId, lines, timeouts, signal) {
     signal?.throwIfAborted();
-    const directory = await import_fs.promises.mkdtemp(path.join((0, import_os.tmpdir)(), "adcp-warehouse-"));
-    const file = path.join(directory, `${jobId}.ndjson`);
-    try {
-      await import_fs.promises.writeFile(file, lines.length ? lines.join("\n") + "\n" : "", { mode: 384 });
+    const table = `the ${role} table "${tableId}" (timeout count ${timeouts})`;
+    let status = await jobStatus(jobId, signal, loadTimeout, table);
+    if (status === "done") return;
+    const loadDeadline = reportingWarehouseLoadDeadlineV1(loadTimeout, timeouts);
+    const deadlineAt = Date.now() + loadDeadline;
+    const timedOut = (what) => {
+      const error = new Error(
+        `${what} exceeded this run's ${loadDeadline} ms deadline for ${table}; the next run checks the job again`
+      );
+      Object.defineProperty(error, "adcpDeadlineExceeded", { value: true });
+      Object.defineProperty(error, "adcpLoadTimedOut", { value: true });
+      return error;
+    };
+    if (status === "missing") {
       try {
-        await withinDeadline(
-          () => dataset.table(tableId).load(file, {
-            jobId,
-            sourceFormat: "NEWLINE_DELIMITED_JSON",
-            writeDisposition: "WRITE_APPEND",
-            ...options.location ? { location: options.location } : {}
-          }),
-          loadDeadline,
-          signal
-        );
+        const running = uploads.get(jobId);
+        const upload = running && Date.now() - running.startedAt < MAX_LOAD_TIMEOUT ? running.done : startUpload(tableId, jobId, lines);
+        await withinDeadline(() => upload, Math.max(deadlineAt - Date.now(), 1), signal);
+        return;
       } catch (error) {
-        if (isDeadlineExceeded(error)) await cancelLoad(jobId, signal);
+        if (isDeadlineExceeded(error)) throw timedOut("Uploading the load");
         if (!isAlreadyExists(error)) throw error;
-        const metadata = await withinDeadline(
-          () => options.bigquery.job(jobId, jobOptions).getMetadata(),
-          loadTimeout,
-          signal
-        );
-        assertJobSucceeded(metadata);
+        status = await jobStatus(jobId, signal, loadTimeout, table);
+        if (status === "missing") {
+          throw new Error(
+            "BigQuery refused the load job ID as already existing, but the job cannot be found. Check that projectId and location match the dataset (location is required for datasets outside the US and EU multi-regions)",
+            { cause: error }
+          );
+        }
       }
-    } finally {
-      await import_fs.promises.rm(directory, { recursive: true, force: true });
+    }
+    const pollMilliseconds = Math.min(5e3, Math.max(250, Math.floor(loadDeadline / 10)));
+    while (status !== "done") {
+      const remaining = deadlineAt - Date.now();
+      if (remaining <= 0) throw timedOut("Waiting for the running load job");
+      await sleep(Math.min(pollMilliseconds, remaining), signal);
+      const bound = Math.max(Math.min(loadTimeout, deadlineAt - Date.now()), 1);
+      try {
+        status = await jobStatus(jobId, signal, bound, table);
+      } catch (error) {
+        if (isDeadlineExceeded(error) && bound < loadTimeout) throw timedOut("Waiting for the running load job");
+        throw error;
+      }
+      if (status === "missing") throw new Error("A BigQuery load job for this batch disappeared while it was awaited");
     }
   }
   return {
@@ -168,6 +229,7 @@ function createBigQueryReportingWarehouseSinkV1(options) {
         `UPDATE adcp_reporting_warehouse_sinks
             SET committed_cursor = NULL, planned_from_cursor = NULL, planned_to_cursor = NULL,
                 planned_revisions = NULL, planned_rows_attempt = 0, planned_revisions_attempt = 0,
+                planned_rows_timeouts = 0, planned_revisions_timeouts = 0,
                 reset_generation = reset_generation + 1, updated_at = clock_timestamp()
           WHERE sink_name = $1 AND ($2::boolean OR planned_to_cursor IS NULL)
           RETURNING sink_name`,
@@ -201,7 +263,8 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       );
       const state = (await options.db.query(
         `SELECT committed_cursor, planned_from_cursor, planned_to_cursor, planned_revisions,
-                  planned_rows_attempt, planned_revisions_attempt, reset_generation
+                  planned_rows_attempt, planned_revisions_attempt,
+                  planned_rows_timeouts, planned_revisions_timeouts, reset_generation
              FROM adcp_reporting_warehouse_sinks WHERE sink_name = $1`,
         [options.name]
       ).catch(missingMigration)).rows[0];
@@ -220,7 +283,9 @@ function createBigQueryReportingWarehouseSinkV1(options) {
         to: state.planned_to_cursor,
         revisions: state.planned_revisions,
         rowsAttempt: state.planned_rows_attempt,
-        revisionsAttempt: state.planned_revisions_attempt
+        revisionsAttempt: state.planned_revisions_attempt,
+        rowsTimeouts: state.planned_rows_timeouts,
+        revisionsTimeouts: state.planned_revisions_timeouts
       } : void 0;
       if (!plan) {
         const position = {
@@ -269,12 +334,15 @@ function createBigQueryReportingWarehouseSinkV1(options) {
           to: page.cursor,
           revisions: page.records.filter((record) => record.kind === "revision").map((record) => ({ id: record.record_id, account_id: record.account_id })),
           rowsAttempt: 0,
-          revisionsAttempt: 0
+          revisionsAttempt: 0,
+          rowsTimeouts: 0,
+          revisionsTimeouts: 0
         };
         const claimed = await options.db.query(
           `UPDATE adcp_reporting_warehouse_sinks
               SET planned_from_cursor = $2, planned_to_cursor = $3, planned_revisions = $4::jsonb,
-                  planned_rows_attempt = 0, planned_revisions_attempt = 0, updated_at = clock_timestamp()
+                  planned_rows_attempt = 0, planned_revisions_attempt = 0,
+                  planned_rows_timeouts = 0, planned_revisions_timeouts = 0, updated_at = clock_timestamp()
             WHERE sink_name = $1 AND committed_cursor IS NOT DISTINCT FROM $2
               AND planned_to_cursor IS NULL AND planned_revisions IS NULL AND reset_generation = $5
             RETURNING sink_name`,
@@ -347,27 +415,52 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       const baseJobId = reportingWarehouseJobIdV1(options.name, plan.from, plan.to, state.reset_generation);
       const suffix = (attempt) => attempt ? `_a${attempt}` : "";
       const steps = [
-        { table: options.rowsTableId, kind: "rows", lines: rowLines, attempt: plan.rowsAttempt },
-        { table: options.revisionsTableId, kind: "revs", lines: revisionLines, attempt: plan.revisionsAttempt }
+        {
+          table: options.rowsTableId,
+          role: "rows",
+          kind: "rows",
+          lines: rowLines,
+          attempt: plan.rowsAttempt,
+          timeouts: plan.rowsTimeouts,
+          timeoutColumn: "planned_rows_timeouts",
+          attemptColumn: "planned_rows_attempt"
+        },
+        {
+          table: options.revisionsTableId,
+          role: "revisions",
+          kind: "revs",
+          lines: revisionLines,
+          attempt: plan.revisionsAttempt,
+          timeouts: plan.revisionsTimeouts,
+          timeoutColumn: "planned_revisions_timeouts",
+          attemptColumn: "planned_revisions_attempt"
+        }
       ];
       for (const step of steps) {
         if (!step.lines.length) continue;
         try {
           await loadOnce(
+            step.role,
             step.table,
             `${baseJobId}_${step.kind}${suffix(step.attempt)}`,
             [...step.lines],
-            step.attempt,
+            step.timeouts,
             signal
           );
         } catch (error) {
           if (isFinishedWithError(error)) {
-            const column = step.kind === "rows" ? "planned_rows_attempt" : "planned_revisions_attempt";
             await options.db.query(
-              `UPDATE adcp_reporting_warehouse_sinks SET ${column} = ${column} + 1,
+              `UPDATE adcp_reporting_warehouse_sinks SET ${step.attemptColumn} = ${step.attemptColumn} + 1,
                       updated_at = clock_timestamp() ${matchesPlan}`,
               planValues
             );
+          } else if (isLoadTimedOut(error)) {
+            await options.db.query(
+              `UPDATE adcp_reporting_warehouse_sinks
+                  SET ${step.timeoutColumn} = $8::integer + 1, updated_at = clock_timestamp()
+                ${matchesPlan} AND ${step.timeoutColumn} = $8::integer`,
+              [...planValues, step.timeouts]
+            );
           }
           throw error;
         }
@@ -376,7 +469,7 @@ function createBigQueryReportingWarehouseSinkV1(options) {
         `UPDATE adcp_reporting_warehouse_sinks
             SET committed_cursor = $3, planned_from_cursor = NULL, planned_to_cursor = NULL,
                 planned_revisions = NULL, planned_rows_attempt = 0, planned_revisions_attempt = 0,
-                updated_at = clock_timestamp()
+                planned_rows_timeouts = 0, planned_revisions_timeouts = 0, updated_at = clock_timestamp()
           ${matchesPlan} RETURNING sink_name`,
         planValues
       );
@@ -395,6 +488,9 @@ function missingMigration(error) {
   }
   throw error;
 }
+function reportingWarehouseLoadDeadlineV1(baseMilliseconds, timeouts) {
+  return Math.min(baseMilliseconds * 2 ** Math.min(Math.max(timeouts, 0), MAX_TIMEOUT_DOUBLINGS), MAX_LOAD_TIMEOUT);
+}
 function reportingWarehouseJobIdV1(name, from, to, generation = 0) {
   return `adcp_rr_${(0, import_crypto.createHash)("sha256").update(JSON.stringify(generation > 0 ? [name, from, to, generation] : [name, from, to])).digest("hex").slice(0, 40)}`;
 }
@@ -467,7 +563,7 @@ function sourceLocalDate(start, timeZone) {
     return instant.toISOString().slice(0, 10);
   }
 }
-async function withinDeadline(operation, milliseconds, signal) {
+async function withinDeadline(operation, milliseconds, signal, context) {
   signal?.throwIfAborted();
   let timer;
   let onAbort;
@@ -476,7 +572,9 @@ async function withinDeadline(operation, milliseconds, signal) {
       operation(),
       new Promise((_, reject) => {
         timer = setTimeout(() => {
-          const error = new Error("BigQuery call exceeded its deadline; the batch will be retried");
+          const error = new Error(
+            `BigQuery call exceeded its deadline${context ? ` of ${milliseconds} ms for ${context}` : ""}; the batch will be retried`
+          );
           Object.defineProperty(error, "adcpDeadlineExceeded", { value: true });
           reject(error);
         }, milliseconds);
@@ -498,25 +596,32 @@ function isAlreadyExists(error) {
   const record = error;
   return record?.code === 409 || !!record?.errors?.some((entry) => entry.reason === "duplicate");
 }
+function isLoadTimedOut(error) {
+  return error?.adcpLoadTimedOut === true;
+}
+function sleep(milliseconds, signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, milliseconds);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function isFinishedWithError(error) {
   return error?.adcpJobFailed === true;
 }
-function assertJobSucceeded(metadata) {
-  const record = Array.isArray(metadata) ? metadata[0] : metadata;
-  if (record?.status?.state !== "DONE") {
-    throw new Error("A BigQuery load job for this batch is still running; retry later");
-  }
-  if (record.status.errorResult) {
-    const failure = new Error("A BigQuery load job for this batch failed; it will be retried as a new attempt");
-    Object.defineProperty(failure, "adcpJobFailed", { value: true });
-    throw failure;
-  }
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   REPORTING_WAREHOUSE_SINK_MIGRATION,
   createBigQueryReportingWarehouseSinkV1,
   reportingWarehouseCurrentRowsViewSqlV1,
   reportingWarehouseDefaultTablesSqlV1,
-  reportingWarehouseJobIdV1
+  reportingWarehouseJobIdV1,
+  reportingWarehouseLoadDeadlineV1
 });

package/dist/lib/reporting/bigquery/index.mjs

@@ -12,14 +12,21 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_warehouse_sinks (
   planned_revisions JSONB,
   planned_rows_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_rows_attempt >= 0),
   planned_revisions_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_revisions_attempt >= 0),
+  planned_rows_timeouts INTEGER NOT NULL DEFAULT 0 CHECK (planned_rows_timeouts >= 0),
+  planned_revisions_timeouts INTEGER NOT NULL DEFAULT 0 CHECK (planned_revisions_timeouts >= 0),
   reset_generation INTEGER NOT NULL DEFAULT 0 CHECK (reset_generation >= 0),
   updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
   CHECK ((planned_to_cursor IS NULL) = (planned_revisions IS NULL))
 );
 ALTER TABLE adcp_reporting_warehouse_sinks
   ADD COLUMN IF NOT EXISTS reset_generation INTEGER NOT NULL DEFAULT 0 CHECK (reset_generation >= 0);
+ALTER TABLE adcp_reporting_warehouse_sinks
+  ADD COLUMN IF NOT EXISTS planned_rows_timeouts INTEGER NOT NULL DEFAULT 0 CHECK (planned_rows_timeouts >= 0);
+ALTER TABLE adcp_reporting_warehouse_sinks
+  ADD COLUMN IF NOT EXISTS planned_revisions_timeouts INTEGER NOT NULL DEFAULT 0 CHECK (planned_revisions_timeouts >= 0);
 `.trim();
 const MAX_LOAD_TIMEOUT = 6 * 36e5;
+const MAX_TIMEOUT_DOUBLINGS = 16;
 let warnedLabelsIgnored = false;
 const PROJECT = /^[a-z][a-z0-9-]{4,61}[a-z0-9]$/;
 const DATASET_OR_TABLE = /^[A-Za-z_][A-Za-z0-9_]{0,1023}$/;
@@ -72,51 +79,104 @@ function createBigQueryReportingWarehouseSinkV1(options) {
     ...options.projectId ? { projectId: options.projectId } : {},
     ...options.location ? { location: options.location } : {}
   } : void 0;
-  async function cancelLoad(jobId, signal) {
+  const uploads = /* @__PURE__ */ new Map();
+  function startUpload(tableId, jobId, lines) {
+    const entry = {
+      startedAt: Date.now(),
+      done: Promise.resolve()
+    };
+    const cleanup = async () => {
+      if (uploads.get(jobId) === entry) uploads.delete(jobId);
+      if (entry.directory) await fs.rm(entry.directory, { recursive: true, force: true }).catch(() => {
+      });
+    };
+    entry.done = (async () => {
+      const directory = await fs.mkdtemp(path.join(tmpdir(), "adcp-warehouse-"));
+      entry.directory = directory;
+      const file = path.join(directory, `${jobId}.ndjson`);
+      await fs.writeFile(file, lines.length ? lines.join("\n") + "\n" : "", { mode: 384 });
+      return dataset.table(tableId).load(file, {
+        jobId,
+        sourceFormat: "NEWLINE_DELIMITED_JSON",
+        writeDisposition: "WRITE_APPEND",
+        ...options.location ? { location: options.location } : {}
+      });
+    })();
+    const replaced = uploads.get(jobId);
+    uploads.set(jobId, entry);
+    void entry.done.then(cleanup, cleanup);
+    if (replaced?.directory) void fs.rm(replaced.directory, { recursive: true, force: true }).catch(() => {
+    });
+    return entry.done;
+  }
+  async function jobStatus(jobId, signal, boundMilliseconds = loadTimeout, context) {
+    let metadata;
     try {
-      const job = options.bigquery.job(jobId, jobOptions);
-      if (typeof job.cancel !== "function") return;
-      const cancel = job.cancel.bind(job);
-      await withinDeadline(cancel, Math.min(loadTimeout, 3e4), signal);
-    } catch (error) {
-      const code = error?.code;
-      if (code === 404 || signal?.aborted) return;
-      process.emitWarning(
-        `Cancelling BigQuery load job ${jobId} failed (${typeof code === "number" || typeof code === "string" ? code : "no status code"}); the job may still be running`,
-        { code: "ADCP_BIGQUERY_SINK_CANCEL_FAILED" }
+      metadata = await withinDeadline(
+        () => options.bigquery.job(jobId, jobOptions).getMetadata(),
+        boundMilliseconds,
+        signal,
+        context
       );
+    } catch (error) {
+      if (error?.code === 404) return "missing";
+      throw error;
     }
+    const record = Array.isArray(metadata) ? metadata[0] : metadata;
+    if (record?.status?.state !== "DONE") return "running";
+    if (record.status.errorResult) {
+      const failure = new Error("A BigQuery load job for this batch failed; it will be retried as a new attempt");
+      Object.defineProperty(failure, "adcpJobFailed", { value: true });
+      throw failure;
+    }
+    return "done";
   }
-  async function loadOnce(tableId, jobId, lines, attempt, signal) {
-    const loadDeadline = Math.min(loadTimeout * 2 ** Math.min(attempt, 16), MAX_LOAD_TIMEOUT);
+  async function loadOnce(role, tableId, jobId, lines, timeouts, signal) {
     signal?.throwIfAborted();
-    const directory = await fs.mkdtemp(path.join(tmpdir(), "adcp-warehouse-"));
-    const file = path.join(directory, `${jobId}.ndjson`);
-    try {
-      await fs.writeFile(file, lines.length ? lines.join("\n") + "\n" : "", { mode: 384 });
+    const table = `the ${role} table "${tableId}" (timeout count ${timeouts})`;
+    let status = await jobStatus(jobId, signal, loadTimeout, table);
+    if (status === "done") return;
+    const loadDeadline = reportingWarehouseLoadDeadlineV1(loadTimeout, timeouts);
+    const deadlineAt = Date.now() + loadDeadline;
+    const timedOut = (what) => {
+      const error = new Error(
+        `${what} exceeded this run's ${loadDeadline} ms deadline for ${table}; the next run checks the job again`
+      );
+      Object.defineProperty(error, "adcpDeadlineExceeded", { value: true });
+      Object.defineProperty(error, "adcpLoadTimedOut", { value: true });
+      return error;
+    };
+    if (status === "missing") {
       try {
-        await withinDeadline(
-          () => dataset.table(tableId).load(file, {
-            jobId,
-            sourceFormat: "NEWLINE_DELIMITED_JSON",
-            writeDisposition: "WRITE_APPEND",
-            ...options.location ? { location: options.location } : {}
-          }),
-          loadDeadline,
-          signal
-        );
+        const running = uploads.get(jobId);
+        const upload = running && Date.now() - running.startedAt < MAX_LOAD_TIMEOUT ? running.done : startUpload(tableId, jobId, lines);
+        await withinDeadline(() => upload, Math.max(deadlineAt - Date.now(), 1), signal);
+        return;
       } catch (error) {
-        if (isDeadlineExceeded(error)) await cancelLoad(jobId, signal);
+        if (isDeadlineExceeded(error)) throw timedOut("Uploading the load");
         if (!isAlreadyExists(error)) throw error;
-        const metadata = await withinDeadline(
-          () => options.bigquery.job(jobId, jobOptions).getMetadata(),
-          loadTimeout,
-          signal
-        );
-        assertJobSucceeded(metadata);
+        status = await jobStatus(jobId, signal, loadTimeout, table);
+        if (status === "missing") {
+          throw new Error(
+            "BigQuery refused the load job ID as already existing, but the job cannot be found. Check that projectId and location match the dataset (location is required for datasets outside the US and EU multi-regions)",
+            { cause: error }
+          );
+        }
       }
-    } finally {
-      await fs.rm(directory, { recursive: true, force: true });
+    }
+    const pollMilliseconds = Math.min(5e3, Math.max(250, Math.floor(loadDeadline / 10)));
+    while (status !== "done") {
+      const remaining = deadlineAt - Date.now();
+      if (remaining <= 0) throw timedOut("Waiting for the running load job");
+      await sleep(Math.min(pollMilliseconds, remaining), signal);
+      const bound = Math.max(Math.min(loadTimeout, deadlineAt - Date.now()), 1);
+      try {
+        status = await jobStatus(jobId, signal, bound, table);
+      } catch (error) {
+        if (isDeadlineExceeded(error) && bound < loadTimeout) throw timedOut("Waiting for the running load job");
+        throw error;
+      }
+      if (status === "missing") throw new Error("A BigQuery load job for this batch disappeared while it was awaited");
     }
   }
   return {
@@ -131,6 +191,7 @@ function createBigQueryReportingWarehouseSinkV1(options) {
         `UPDATE adcp_reporting_warehouse_sinks
             SET committed_cursor = NULL, planned_from_cursor = NULL, planned_to_cursor = NULL,
                 planned_revisions = NULL, planned_rows_attempt = 0, planned_revisions_attempt = 0,
+                planned_rows_timeouts = 0, planned_revisions_timeouts = 0,
                 reset_generation = reset_generation + 1, updated_at = clock_timestamp()
           WHERE sink_name = $1 AND ($2::boolean OR planned_to_cursor IS NULL)
           RETURNING sink_name`,
@@ -164,7 +225,8 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       );
       const state = (await options.db.query(
         `SELECT committed_cursor, planned_from_cursor, planned_to_cursor, planned_revisions,
-                  planned_rows_attempt, planned_revisions_attempt, reset_generation
+                  planned_rows_attempt, planned_revisions_attempt,
+                  planned_rows_timeouts, planned_revisions_timeouts, reset_generation
              FROM adcp_reporting_warehouse_sinks WHERE sink_name = $1`,
         [options.name]
       ).catch(missingMigration)).rows[0];
@@ -183,7 +245,9 @@ function createBigQueryReportingWarehouseSinkV1(options) {
         to: state.planned_to_cursor,
         revisions: state.planned_revisions,
         rowsAttempt: state.planned_rows_attempt,
-        revisionsAttempt: state.planned_revisions_attempt
+        revisionsAttempt: state.planned_revisions_attempt,
+        rowsTimeouts: state.planned_rows_timeouts,
+        revisionsTimeouts: state.planned_revisions_timeouts
       } : void 0;
       if (!plan) {
         const position = {
@@ -232,12 +296,15 @@ function createBigQueryReportingWarehouseSinkV1(options) {
           to: page.cursor,
           revisions: page.records.filter((record) => record.kind === "revision").map((record) => ({ id: record.record_id, account_id: record.account_id })),
           rowsAttempt: 0,
-          revisionsAttempt: 0
+          revisionsAttempt: 0,
+          rowsTimeouts: 0,
+          revisionsTimeouts: 0
         };
         const claimed = await options.db.query(
           `UPDATE adcp_reporting_warehouse_sinks
               SET planned_from_cursor = $2, planned_to_cursor = $3, planned_revisions = $4::jsonb,
-                  planned_rows_attempt = 0, planned_revisions_attempt = 0, updated_at = clock_timestamp()
+                  planned_rows_attempt = 0, planned_revisions_attempt = 0,
+                  planned_rows_timeouts = 0, planned_revisions_timeouts = 0, updated_at = clock_timestamp()
             WHERE sink_name = $1 AND committed_cursor IS NOT DISTINCT FROM $2
               AND planned_to_cursor IS NULL AND planned_revisions IS NULL AND reset_generation = $5
             RETURNING sink_name`,
@@ -310,27 +377,52 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       const baseJobId = reportingWarehouseJobIdV1(options.name, plan.from, plan.to, state.reset_generation);
       const suffix = (attempt) => attempt ? `_a${attempt}` : "";
       const steps = [
-        { table: options.rowsTableId, kind: "rows", lines: rowLines, attempt: plan.rowsAttempt },
-        { table: options.revisionsTableId, kind: "revs", lines: revisionLines, attempt: plan.revisionsAttempt }
+        {
+          table: options.rowsTableId,
+          role: "rows",
+          kind: "rows",
+          lines: rowLines,
+          attempt: plan.rowsAttempt,
+          timeouts: plan.rowsTimeouts,
+          timeoutColumn: "planned_rows_timeouts",
+          attemptColumn: "planned_rows_attempt"
+        },
+        {
+          table: options.revisionsTableId,
+          role: "revisions",
+          kind: "revs",
+          lines: revisionLines,
+          attempt: plan.revisionsAttempt,
+          timeouts: plan.revisionsTimeouts,
+          timeoutColumn: "planned_revisions_timeouts",
+          attemptColumn: "planned_revisions_attempt"
+        }
       ];
       for (const step of steps) {
         if (!step.lines.length) continue;
         try {
           await loadOnce(
+            step.role,
             step.table,
             `${baseJobId}_${step.kind}${suffix(step.attempt)}`,
             [...step.lines],
-            step.attempt,
+            step.timeouts,
             signal
           );
         } catch (error) {
           if (isFinishedWithError(error)) {
-            const column = step.kind === "rows" ? "planned_rows_attempt" : "planned_revisions_attempt";
             await options.db.query(
-              `UPDATE adcp_reporting_warehouse_sinks SET ${column} = ${column} + 1,
+              `UPDATE adcp_reporting_warehouse_sinks SET ${step.attemptColumn} = ${step.attemptColumn} + 1,
                       updated_at = clock_timestamp() ${matchesPlan}`,
               planValues
             );
+          } else if (isLoadTimedOut(error)) {
+            await options.db.query(
+              `UPDATE adcp_reporting_warehouse_sinks
+                  SET ${step.timeoutColumn} = $8::integer + 1, updated_at = clock_timestamp()
+                ${matchesPlan} AND ${step.timeoutColumn} = $8::integer`,
+              [...planValues, step.timeouts]
+            );
           }
           throw error;
         }
@@ -339,7 +431,7 @@ function createBigQueryReportingWarehouseSinkV1(options) {
         `UPDATE adcp_reporting_warehouse_sinks
             SET committed_cursor = $3, planned_from_cursor = NULL, planned_to_cursor = NULL,
                 planned_revisions = NULL, planned_rows_attempt = 0, planned_revisions_attempt = 0,
-                updated_at = clock_timestamp()
+                planned_rows_timeouts = 0, planned_revisions_timeouts = 0, updated_at = clock_timestamp()
           ${matchesPlan} RETURNING sink_name`,
         planValues
       );
@@ -358,6 +450,9 @@ function missingMigration(error) {
   }
   throw error;
 }
+function reportingWarehouseLoadDeadlineV1(baseMilliseconds, timeouts) {
+  return Math.min(baseMilliseconds * 2 ** Math.min(Math.max(timeouts, 0), MAX_TIMEOUT_DOUBLINGS), MAX_LOAD_TIMEOUT);
+}
 function reportingWarehouseJobIdV1(name, from, to, generation = 0) {
   return `adcp_rr_${createHash("sha256").update(JSON.stringify(generation > 0 ? [name, from, to, generation] : [name, from, to])).digest("hex").slice(0, 40)}`;
 }
@@ -430,7 +525,7 @@ function sourceLocalDate(start, timeZone) {
     return instant.toISOString().slice(0, 10);
   }
 }
-async function withinDeadline(operation, milliseconds, signal) {
+async function withinDeadline(operation, milliseconds, signal, context) {
   signal?.throwIfAborted();
   let timer;
   let onAbort;
@@ -439,7 +534,9 @@ async function withinDeadline(operation, milliseconds, signal) {
       operation(),
       new Promise((_, reject) => {
         timer = setTimeout(() => {
-          const error = new Error("BigQuery call exceeded its deadline; the batch will be retried");
+          const error = new Error(
+            `BigQuery call exceeded its deadline${context ? ` of ${milliseconds} ms for ${context}` : ""}; the batch will be retried`
+          );
           Object.defineProperty(error, "adcpDeadlineExceeded", { value: true });
           reject(error);
         }, milliseconds);
@@ -461,24 +558,31 @@ function isAlreadyExists(error) {
   const record = error;
   return record?.code === 409 || !!record?.errors?.some((entry) => entry.reason === "duplicate");
 }
+function isLoadTimedOut(error) {
+  return error?.adcpLoadTimedOut === true;
+}
+function sleep(milliseconds, signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, milliseconds);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function isFinishedWithError(error) {
   return error?.adcpJobFailed === true;
 }
-function assertJobSucceeded(metadata) {
-  const record = Array.isArray(metadata) ? metadata[0] : metadata;
-  if (record?.status?.state !== "DONE") {
-    throw new Error("A BigQuery load job for this batch is still running; retry later");
-  }
-  if (record.status.errorResult) {
-    const failure = new Error("A BigQuery load job for this batch failed; it will be retried as a new attempt");
-    Object.defineProperty(failure, "adcpJobFailed", { value: true });
-    throw failure;
-  }
-}
 export {
   REPORTING_WAREHOUSE_SINK_MIGRATION,
   createBigQueryReportingWarehouseSinkV1,
   reportingWarehouseCurrentRowsViewSqlV1,
   reportingWarehouseDefaultTablesSqlV1,
-  reportingWarehouseJobIdV1
+  reportingWarehouseJobIdV1,
+  reportingWarehouseLoadDeadlineV1
 };

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-10-13T02:34:34.174Z"
+  "synced_at": "2026-10-14T11:39:27.882Z"
 }

package/dist/lib/testing/storyboard/validations.d.mts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "15.9.0";
+export declare const RUNNER_CAPABILITY_VERSION = "15.9.1";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.d.ts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "15.9.0";
+export declare const RUNNER_CAPABILITY_VERSION = "15.9.1";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "15.9.0";
+export declare const LIBRARY_VERSION = "15.9.1";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "15.9.0";
+    readonly library: "15.9.1";
     readonly adcp: "3.2.4";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4"];
-    readonly generatedAt: "2026-10-13T01:26:11.275Z";
+    readonly generatedAt: "2026-10-14T11:09:46.080Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "15.9.0";
+export declare const LIBRARY_VERSION = "15.9.1";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "15.9.0";
+    readonly library: "15.9.1";
     readonly adcp: "3.2.4";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4"];
-    readonly generatedAt: "2026-10-13T01:26:11.275Z";
+    readonly generatedAt: "2026-10-14T11:09:46.080Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.js

@@ -31,7 +31,7 @@ __export(version_exports, {
   toReleasePrecisionVersion: () => toReleasePrecisionVersion
 });
 module.exports = __toCommonJS(version_exports);
-const LIBRARY_VERSION = "15.9.0";
+const LIBRARY_VERSION = "15.9.1";
 const ADCP_VERSION = "3.2.4";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -98,10 +98,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.4"
 ];
 const VERSION_INFO = {
-  library: "15.9.0",
+  library: "15.9.1",
   adcp: "3.2.4",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-13T01:26:11.275Z"
+  generatedAt: "2026-10-14T11:09:46.080Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "15.9.0";
+const LIBRARY_VERSION = "15.9.1";
 const ADCP_VERSION = "3.2.4";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -65,10 +65,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.4"
 ];
 const VERSION_INFO = {
-  library: "15.9.0",
+  library: "15.9.1",
   adcp: "3.2.4",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-13T01:26:11.275Z"
+  generatedAt: "2026-10-14T11:09:46.080Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-13
-> @adcp/sdk v15.9.0
+> Generated at: 2026-10-14
+> @adcp/sdk v15.9.1
 
 Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
 

package/docs/guides/REPORTING-LEDGER.md

@@ -911,29 +911,53 @@ setInterval(() => {
   `revision_number`, `finality`, `period_date` (the period's date in its source
   timezone) and `ordinal` to your mapped columns.
 - Batches are planned durably before loading, and job IDs derive from the
-  change-feed range. A crash between a load and the cursor commit replays the
-  same batch under the same job ID, which BigQuery refuses to run twice. A job
-  that finished with an error is retried under a new attempt for that table
-  only.
+  change-feed range. Before every submission the sink looks that job ID up in
+  the destination project and location: a job that finished cleanly counts as
+  loaded, a job that is pending or running is waited for (never uploaded
+  again), and only a missing job (404) is uploaded. A crash or timeout between a
+  load and the cursor commit therefore replays the same batch under the same
+  job ID without a second upload. An upload an earlier run abandoned at its
+  deadline is still running in the same process (the official client cannot
+  abort it), so the next run waits for it, within its own deadline, rather than
+  starting another, however long ago it started (that age includes the gap
+  between runs). If that wait outlasts the run's deadline it counts as a timeout
+  and the deadline grows. Only an upload still pending after 6 hours, the
+  largest deadline, is abandoned and replaced; BigQuery refuses a duplicate job
+  ID, so a replacement can never load the batch twice. A job that finished with
+  an error is retried under a new attempt for that table only. Deadline and
+  timeout errors name the table (`rows` or `revisions`, and its ID), the
+  deadline in force and that table's timeout count, never a file path or
+  credential.
 - `projectId` scopes both load submission and replay status checks. When it is
   omitted, both use the BigQuery client's default project. Each replica must
-  be able to read the BigQuery jobs submitted by the other replicas.
-- `loadTimeoutMilliseconds` (default 10 minutes) is a client-side deadline for
-  one load. When a load passes it, the sink asks BigQuery to cancel that job by
-  its deterministic ID, in `projectId` and `location`, and rejects with the
-  plan retained. The next run finds the cancelled job finished with an error,
-  advances that table's attempt and rejects; the run after that loads under the
-  new attempt. If the cancel has not taken effect yet it waits for the job.
-  Each attempt doubles the load deadline (up to 6 hours), so a slow but healthy
-  load converges; set the deadline above your slowest expected load to avoid
-  the cancelled attempts. Cancellation is best effort (BigQuery may finish the
-  job anyway, which the next run then accepts), a failed cancel other than "not
-  found" raises a `ADCP_BIGQUERY_SINK_CANCEL_FAILED` process warning, and a
-  status check that times out is not cancelled. BigQuery's server-side
-  `jobTimeoutMs` is not used: for a local-file load the official client builds
-  `configuration.load` from the load options and cannot set job-level fields,
-  and BigQuery silently drops `labels` and `jobTimeoutMs` found inside
-  `configuration.load`. (Staging the file in GCS and submitting the load with
+  be able to read the BigQuery jobs submitted by the other replicas. Set
+  `location` for any dataset outside the US and EU multi-regions: BigQuery
+  answers a job lookup without the right location with 404, and the sink then
+  cannot find the jobs it created.
+- `loadTimeoutMilliseconds` (default 10 minutes) is the base deadline for one
+  run's work on one load: uploading the file, or waiting for a job that is still
+  running. It bounds a run, not the job. BigQuery does not stop a load when the
+  client gives up (a cancel is accepted and the job finishes anyway), and it
+  refuses a resubmitted job ID only after the whole file is uploaded again, so
+  the sink never cancels and never relies on that refusal. When the deadline
+  passes, the run rejects with the plan retained and nothing advanced: the job
+  ID, the attempt and the cursor stay as they were, and the next run looks the
+  job up by its ID again. A job whose upload outlasted a deadline is created in
+  the background and is picked up by the next run with no second upload. Each
+  such timeout doubles that table's deadline for later runs (up to 6 hours).
+  The growth is kept with the plan in `planned_rows_timeouts` and
+  `planned_revisions_timeouts` (so it survives restarts and applies to every
+  replica, and clears when the batch commits), so an upload slower than the
+  deadline eventually gets enough time. Set the deadline above your slowest
+  expected load to avoid the extra runs. Only a job BigQuery reports as
+  finished with an error advances the attempt. A status check that times out
+  is bounded by the base deadline and does not grow it. Re-run
+  `REPORTING_WAREHOUSE_SINK_MIGRATION` after upgrading: it adds the two timeout
+  columns (a sink table without them rejects with a message saying so).
+  BigQuery's server-side `jobTimeoutMs` is not used: for a local-file load the
+  official client builds `configuration.load` from the load options and cannot
+  set job-level fields, and BigQuery silently drops `labels` and `jobTimeoutMs`
+  found inside `configuration.load`. (Staging the file in GCS and submitting the load with
   `bigquery.createJob` can set both; the sink does not stage files.) For the
   same reason the `labels` option has no effect (it warns once per process and
   is deprecated). To attribute load cost, query
@@ -974,7 +998,9 @@ setInterval(() => {
   jobs may have succeeded; reconcile the plan against BigQuery, then call
   `reset({ discardRetainedPlan: true })`. It does not touch the warehouse: a sink
   that already loaded history reloads the retained revisions, so empty the
-  destination tables first or use a new sink name against new tables. Every
+  destination tables first (after stopping every worker and letting in-flight
+  uploads and jobs finish, since the sink never cancels a load) or use a new
+  sink name against new tables. Every
   reset starts a new job ID generation, so reloaded batches submit fresh BigQuery
   jobs instead of matching the finished jobs of the earlier history. Nothing holds
   change retention between `reset()` and the first committed batch. If `reset()`

package/docs/guides/REPORTING-OPERATIONS.md

@@ -334,9 +334,20 @@ What it checks:
   duplicate rows, and that `current_rows` returns one revision per obligation.
   It also asserts (`PASS`/`FAIL`) that the sink sends no `labels` or
   `jobTimeoutMs` inside `configuration.load`, where BigQuery silently drops
-  them, and that a job cancel addressed with the destination project and
-  location (what the sink sends when a load passes its client-side deadline) is
-  accepted by BigQuery.
+  them. A deadline scenario runs a sink with the minimum 1-second load deadline
+  and holds the first load's result past it: the run must reject with the plan
+  and job ID unchanged and that table's persisted deadline grown, the job must
+  end `DONE` without an error (the sink never cancels it), and later runs under
+  the same sink name must converge with no duplicate rows, the same job ID and
+  no second upload. A #3234 scenario runs a sink whose upload of a 50,000-row
+  batch outlasts its 1-second deadline and asserts that it converges within 8
+  runs, loads every row exactly once, never changes the job ID, and never
+  starts an upload after the job exists (a link fast enough to beat the
+  deadline passes and says so).
+- **Cancel probe of the service** (`INFO`, never a failure). It cancels a
+  5000-row load the moment it is created and reports whether BigQuery stopped
+  it; in practice it accepts the cancel and lets the load finish, which is why
+  the sink never cancels a load and finds it by job ID instead.
 - **Overlapping runs** (`INFO`, never a failure). Two concurrent `runOnce()`
   calls over one pending batch, and a deterministic reproduction of #3196: one
   run reads its sink state, another completes the batch and a new revision

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-13
-> Library: @adcp/sdk v15.9.0
+> Generated at: 2026-10-14
+> Library: @adcp/sdk v15.9.1
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.

package/docs/migration-14.x-rc-worksheet.md

@@ -11,8 +11,8 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@15.9.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.9.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@15.9.1` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.9.1 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.4` |
 | Maintained wire releases | `v2.5`, `v2.6`, `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4` |
@@ -21,8 +21,8 @@ below as the publication/deployment gate.
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@15.9.0'
-npm view '@adcp/sdk@15.9.0' dist.integrity
+npm install --save-exact '@adcp/sdk@15.9.1'
+npm view '@adcp/sdk@15.9.1' dist.integrity
 ```
 
 ### Required and optional peers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "15.9.0",
+  "version": "15.9.1",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",