@adcp/sdk 15.2.2 → 15.4.0

package/dist/lib/reporting/ledger/row-encoding.mjs

@@ -0,0 +1,315 @@
+import { createHash } from "crypto";
+import { canonicalize } from "../../utils/jcs.mjs";
+const REPORTING_ROW_ENCODING_V1 = "adcp_canonical_jsonl_v1";
+const REPORTING_ROW_SEGMENT_MAX_ROWS = 500;
+const REPORTING_ROW_CHUNK_MAX_SEGMENTS = 20;
+const REPORTING_ROW_CHUNK_MAX_ROWS = REPORTING_ROW_SEGMENT_MAX_ROWS * REPORTING_ROW_CHUNK_MAX_SEGMENTS;
+const REPORTING_ROW_CHUNK_MAX_BYTES = 8 * 1024 * 1024;
+const NEWLINE = 10;
+const COMMA = Buffer.from(",", "utf8");
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+class ReportingRowEncodingError extends Error {
+  constructor(code, detail) {
+    super(`Reporting row encoding: ${code}: ${detail}`);
+    this.code = code;
+    this.name = "ReportingRowEncodingError";
+    Object.defineProperty(this, /* @__PURE__ */ Symbol.for("adcp.reportingRowEncodingError"), { value: true });
+  }
+  code;
+}
+function isReportingRowEncodingError(error) {
+  return !!error && typeof error === "object" && error[/* @__PURE__ */ Symbol.for("adcp.reportingRowEncodingError")] === true;
+}
+function canonicalReportingRowV1(row, ordinal = 0) {
+  if (!row || typeof row !== "object" || Array.isArray(row)) {
+    throw new ReportingRowEncodingError("INVALID_ROW", `row ${ordinal} is not a JSON object`);
+  }
+  assertPortableNumbers(row, ordinal);
+  let canonical;
+  try {
+    canonical = canonicalize(row);
+  } catch (error) {
+    throw new ReportingRowEncodingError(
+      "INVALID_ROW",
+      `row ${ordinal} is not canonical JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (LONE_SURROGATE.test(canonical)) {
+    throw new ReportingRowEncodingError("INVALID_ROW", `row ${ordinal} contains a lone surrogate`);
+  }
+  return canonical;
+}
+function encodeReportingRowsV1(rows) {
+  const chunks = [];
+  let chunkLines = [];
+  let chunkBytes = 0;
+  let chunkFirstOrdinal = 0;
+  const closeChunk = () => {
+    if (chunkLines.length === 0) return;
+    chunks.push(buildChunk(chunks.length, chunkFirstOrdinal, chunkLines));
+    chunkLines = [];
+    chunkBytes = 0;
+  };
+  rows.forEach((row, ordinal) => {
+    const line = Buffer.from(canonicalReportingRowV1(row, ordinal) + "\n", "utf8");
+    if (chunkLines.length === REPORTING_ROW_CHUNK_MAX_ROWS || chunkLines.length > 0 && chunkBytes + line.byteLength > REPORTING_ROW_CHUNK_MAX_BYTES) {
+      closeChunk();
+    }
+    if (chunkLines.length === 0) chunkFirstOrdinal = ordinal;
+    chunkLines.push(line);
+    chunkBytes += line.byteLength;
+  });
+  closeChunk();
+  const manifests = chunks.map((chunk) => chunk.manifest);
+  return {
+    encoding: REPORTING_ROW_ENCODING_V1,
+    rowCount: rows.length,
+    byteCount: chunks.reduce((total, chunk) => total + chunk.manifest.byte_count, 0),
+    chunks,
+    manifests,
+    rowManifestSha256: reportingRowManifestSha256V1(manifests)
+  };
+}
+function reportingRowManifestSha256V1(manifests) {
+  return sha256Hex(
+    canonicalize(
+      manifests.map((manifest) => ({
+        chunk_index: manifest.chunk_index,
+        first_ordinal: manifest.first_ordinal,
+        row_count: manifest.row_count,
+        byte_count: manifest.byte_count,
+        sha256: manifest.sha256,
+        segments: manifest.segments.map((segment) => ({
+          first_ordinal: segment.first_ordinal,
+          row_count: segment.row_count,
+          byte_offset: segment.byte_offset,
+          byte_count: segment.byte_count,
+          sha256: segment.sha256
+        }))
+      }))
+    )
+  );
+}
+function verifyReportingRowManifestsV1(manifests, expected) {
+  if (reportingRowManifestSha256V1(manifests) !== expected.rowManifestSha256.toLowerCase()) {
+    throw new ReportingRowEncodingError("MANIFEST_MISMATCH", "chunk manifest digest does not match the header");
+  }
+  let nextOrdinal = 0;
+  manifests.forEach((manifest, index) => {
+    if (manifest.chunk_index !== index || manifest.first_ordinal !== nextOrdinal) {
+      throw new ReportingRowEncodingError("MANIFEST_MISMATCH", `chunk ${index} is out of order`);
+    }
+    if (manifest.row_count < 1 || manifest.row_count > REPORTING_ROW_CHUNK_MAX_ROWS || manifest.segments.length < 1 || manifest.segments.length > REPORTING_ROW_CHUNK_MAX_SEGMENTS) {
+      throw new ReportingRowEncodingError("MANIFEST_MISMATCH", `chunk ${index} exceeds contract limits`);
+    }
+    let segmentOrdinal = manifest.first_ordinal;
+    let segmentOffset = 0;
+    manifest.segments.forEach((segment, segmentIndex) => {
+      const last = segmentIndex === manifest.segments.length - 1;
+      if (segment.first_ordinal !== segmentOrdinal || segment.byte_offset !== segmentOffset || segment.row_count < 1 || segment.byte_count < 1 || segment.row_count > REPORTING_ROW_SEGMENT_MAX_ROWS || !last && segment.row_count !== REPORTING_ROW_SEGMENT_MAX_ROWS) {
+        throw new ReportingRowEncodingError("MANIFEST_MISMATCH", `chunk ${index} segment ${segmentIndex} is invalid`);
+      }
+      segmentOrdinal += segment.row_count;
+      segmentOffset += segment.byte_count;
+    });
+    if (segmentOrdinal !== manifest.first_ordinal + manifest.row_count || segmentOffset !== manifest.byte_count) {
+      throw new ReportingRowEncodingError("MANIFEST_MISMATCH", `chunk ${index} segments do not tile the chunk`);
+    }
+    if (manifest.row_count > 1 && manifest.byte_count > REPORTING_ROW_CHUNK_MAX_BYTES) {
+      throw new ReportingRowEncodingError("MANIFEST_MISMATCH", `chunk ${index} exceeds the byte limit`);
+    }
+    nextOrdinal += manifest.row_count;
+  });
+  if (nextOrdinal !== expected.rowCount) {
+    throw new ReportingRowEncodingError("MANIFEST_MISMATCH", "chunk manifests do not cover row_count");
+  }
+}
+function verifyReportingRowChunkV1(manifest, bytes) {
+  const buffer = toBuffer(bytes);
+  if (buffer.byteLength !== manifest.byte_count || sha256Hex(buffer) !== manifest.sha256) {
+    throw new ReportingRowEncodingError("CHUNK_INTEGRITY_FAILED", `chunk ${manifest.chunk_index} digest mismatch`);
+  }
+  manifest.segments.forEach((segment, index) => {
+    verifySegment(manifest, index, buffer.subarray(segment.byte_offset, segment.byte_offset + segment.byte_count));
+  });
+}
+function decodeVerifiedReportingRowSegmentsV1(manifest, segmentRange, bytes) {
+  const [from, to] = segmentRange;
+  if (!Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to < from || to >= manifest.segments.length) {
+    throw new ReportingRowEncodingError("MANIFEST_MISMATCH", "segment range is outside the chunk");
+  }
+  const buffer = toBuffer(bytes);
+  const base = manifest.segments[from].byte_offset;
+  const end = manifest.segments[to].byte_offset + manifest.segments[to].byte_count;
+  if (buffer.byteLength !== end - base) {
+    throw new ReportingRowEncodingError("CHUNK_INTEGRITY_FAILED", "segment range byte length mismatch");
+  }
+  for (let index = from; index <= to; index += 1) {
+    const segment = manifest.segments[index];
+    verifySegment(
+      manifest,
+      index,
+      buffer.subarray(segment.byte_offset - base, segment.byte_offset - base + segment.byte_count)
+    );
+  }
+  return splitLines(buffer).map((line) => JSON.parse(line.toString("utf8")));
+}
+function createReportingRevisionEnvelopeHasherV1(envelope) {
+  const prefix = Buffer.from(
+    `{"control_totals":${canonicalize(envelope.control_totals)},"reporting_revision_id":${canonicalize(
+      envelope.reporting_revision_id
+    )},"reporting_rows":[`,
+    "utf8"
+  );
+  const suffix = Buffer.from(`],"row_count":${canonicalize(envelope.row_count)}}`, "utf8");
+  return createJoinedRowsHasher(prefix, suffix, envelope.row_count);
+}
+function reportingRevisionEnvelopeDigestV1(envelope, chunks) {
+  const hasher = createReportingRevisionEnvelopeHasherV1(envelope);
+  for (const chunk of chunks) hasher.update(chunk);
+  return hasher.digest();
+}
+function createReportingRowsOnlyHasherV1(rowCount) {
+  return createJoinedRowsHasher(Buffer.from("[", "utf8"), Buffer.from("]", "utf8"), rowCount);
+}
+function assertReportingRevisionEnvelopeV1(envelope, chunks, expected) {
+  const actual = reportingRevisionEnvelopeDigestV1(envelope, chunks);
+  if (actual.sha256 !== expected.sha256.toLowerCase() || expected.byteCount !== void 0 && actual.byteCount !== expected.byteCount) {
+    throw new ReportingRowEncodingError("ENVELOPE_INTEGRITY_FAILED", "revision content binding mismatch");
+  }
+}
+function buildChunk(chunkIndex, firstOrdinal, lines) {
+  const segments = [];
+  let offset = 0;
+  for (let start = 0; start < lines.length; start += REPORTING_ROW_SEGMENT_MAX_ROWS) {
+    const segmentLines = lines.slice(start, start + REPORTING_ROW_SEGMENT_MAX_ROWS);
+    const segmentBytes = Buffer.concat(segmentLines);
+    segments.push({
+      first_ordinal: firstOrdinal + start,
+      row_count: segmentLines.length,
+      byte_offset: offset,
+      byte_count: segmentBytes.byteLength,
+      sha256: sha256Hex(segmentBytes)
+    });
+    offset += segmentBytes.byteLength;
+  }
+  const bytes = Buffer.concat(lines);
+  return {
+    manifest: {
+      chunk_index: chunkIndex,
+      first_ordinal: firstOrdinal,
+      row_count: lines.length,
+      byte_count: bytes.byteLength,
+      sha256: sha256Hex(bytes),
+      segments
+    },
+    bytes
+  };
+}
+function verifySegment(manifest, index, bytes) {
+  const segment = manifest.segments[index];
+  if (bytes.byteLength !== segment.byte_count || sha256Hex(bytes) !== segment.sha256) {
+    throw new ReportingRowEncodingError(
+      "CHUNK_INTEGRITY_FAILED",
+      `chunk ${manifest.chunk_index} segment ${index} digest mismatch`
+    );
+  }
+  let lines = 0;
+  for (const byte of bytes) if (byte === NEWLINE) lines += 1;
+  if (lines !== segment.row_count || bytes[bytes.byteLength - 1] !== NEWLINE) {
+    throw new ReportingRowEncodingError(
+      "CHUNK_INTEGRITY_FAILED",
+      `chunk ${manifest.chunk_index} segment ${index} line count mismatch`
+    );
+  }
+}
+function createJoinedRowsHasher(prefix, suffix, expectedRows) {
+  const hash = createHash("sha256").update(prefix);
+  let byteCount = prefix.byteLength;
+  let rows = 0;
+  let finished = false;
+  return {
+    update(chunkBytes) {
+      if (finished) throw new Error("Reporting row hasher already finished");
+      const buffer = toBuffer(chunkBytes);
+      if (buffer.byteLength > 0 && buffer[buffer.byteLength - 1] !== NEWLINE) {
+        throw new ReportingRowEncodingError("CHUNK_INTEGRITY_FAILED", "chunk does not end at a row boundary");
+      }
+      for (const line of splitLines(buffer)) {
+        if (rows > 0) {
+          hash.update(COMMA);
+          byteCount += 1;
+        }
+        hash.update(line);
+        byteCount += line.byteLength;
+        rows += 1;
+      }
+    },
+    digest() {
+      if (finished) throw new Error("Reporting row hasher already finished");
+      finished = true;
+      if (rows !== expectedRows) {
+        throw new ReportingRowEncodingError("ENVELOPE_INTEGRITY_FAILED", "row count does not match the header");
+      }
+      hash.update(suffix);
+      return { sha256: hash.digest("hex"), byteCount: byteCount + suffix.byteLength };
+    }
+  };
+}
+function splitLines(buffer) {
+  const lines = [];
+  let start = 0;
+  for (let index = 0; index < buffer.byteLength; index += 1) {
+    if (buffer[index] === NEWLINE) {
+      lines.push(buffer.subarray(start, index));
+      start = index + 1;
+    }
+  }
+  if (start !== buffer.byteLength) {
+    throw new ReportingRowEncodingError("CHUNK_INTEGRITY_FAILED", "trailing bytes after the last row");
+  }
+  return lines;
+}
+function assertPortableNumbers(value, ordinal) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value)) {
+      throw new ReportingRowEncodingError(
+        "INVALID_ROW",
+        `row ${ordinal} contains a number outside the portable range; encode it as a string`
+      );
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) assertPortableNumbers(item, ordinal);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const item of Object.values(value)) assertPortableNumbers(item, ordinal);
+  }
+}
+function toBuffer(bytes) {
+  return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+function sha256Hex(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+export {
+  REPORTING_ROW_CHUNK_MAX_BYTES,
+  REPORTING_ROW_CHUNK_MAX_ROWS,
+  REPORTING_ROW_CHUNK_MAX_SEGMENTS,
+  REPORTING_ROW_ENCODING_V1,
+  REPORTING_ROW_SEGMENT_MAX_ROWS,
+  ReportingRowEncodingError,
+  assertReportingRevisionEnvelopeV1,
+  canonicalReportingRowV1,
+  createReportingRevisionEnvelopeHasherV1,
+  createReportingRowsOnlyHasherV1,
+  decodeVerifiedReportingRowSegmentsV1,
+  encodeReportingRowsV1,
+  isReportingRowEncodingError,
+  reportingRevisionEnvelopeDigestV1,
+  reportingRowManifestSha256V1,
+  verifyReportingRowChunkV1,
+  verifyReportingRowManifestsV1
+};

package/dist/lib/reporting/ledger/types.d.mts

@@ -198,6 +198,21 @@ export interface ReportingLedgerAdjustmentV1 {
 }
 export type ReportingLedgerRevisionSnapshotV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
 export type ReportingLedgerRevisionMetadataV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
+export type ReportingLedgerAdjustmentMetadataV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
+export interface ReportingRevisionRowsReadV1 {
+    reporting_revision_id: string;
+    account_id: string;
+    /** Zero-based ordinal of the first row to return. */
+    offset: number;
+    /** Maximum rows to return; at least 1. */
+    limit: number;
+    signal?: AbortSignal;
+}
+export interface ReportingRevisionRowsPageV1 {
+    rows: Record<string, unknown>[];
+    /** Total rows in the revision. */
+    total: number;
+}
 export type ReportingLedgerAdjustmentSnapshotV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
 export interface ReportingLedgerConsumerStatusV1 {
     consumerStatusId: string;
@@ -761,12 +776,34 @@ export interface ReportingLedgerStore {
     }>;
     /** Returns an exact row-bearing revision only when it belongs to the resolved account. */
     getRevision(reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionV1 | null>;
+    /**
+     * Optional row-free counterpart of `getRevision`, scoped to the resolved
+     * account. Exact-read handlers prefer it so they never load every row to
+     * serve one page.
+     */
+    getRevisionMetadata?(reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+    /**
+     * Optional: one page of a revision's rows in ordinal order, only when the
+     * revision belongs to the resolved account. `total` is the revision's row
+     * count. Stores that keep rows outside the revision document verify every
+     * row they return against the committed binding before returning it.
+     */
+    readRevisionRows?(input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;
     listRevisions(reporting_obligation_id: string): Promise<ReportingLedgerRevisionV1[]>;
+    /**
+     * Optional: every retained revision for one obligation without
+     * materializing rows. The producer, lifecycle reconciler and status ingest
+     * prefer it and otherwise fall back to `listRevisions` with rows dropped.
+     * When `account_id` is supplied, only that account's revisions are returned.
+     */
+    listRevisionMetadata?(reporting_obligation_id: string, account_id?: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
     commitAdjustment(adjustment: ReportingLedgerAdjustmentV1, lease: ReportingLedgerLeaseV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerAdjustmentV1;
     }>;
     listAdjustments(reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentV1[]>;
+    /** Optional row-free counterpart of `listAdjustments`, preferred when present. */
+    listAdjustmentMetadata?(reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
     putConsumerStatus(status: ReportingLedgerConsumerStatusV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerConsumerStatusV1;

package/dist/lib/reporting/ledger/types.d.ts

@@ -198,6 +198,21 @@ export interface ReportingLedgerAdjustmentV1 {
 }
 export type ReportingLedgerRevisionSnapshotV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
 export type ReportingLedgerRevisionMetadataV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
+export type ReportingLedgerAdjustmentMetadataV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
+export interface ReportingRevisionRowsReadV1 {
+    reporting_revision_id: string;
+    account_id: string;
+    /** Zero-based ordinal of the first row to return. */
+    offset: number;
+    /** Maximum rows to return; at least 1. */
+    limit: number;
+    signal?: AbortSignal;
+}
+export interface ReportingRevisionRowsPageV1 {
+    rows: Record<string, unknown>[];
+    /** Total rows in the revision. */
+    total: number;
+}
 export type ReportingLedgerAdjustmentSnapshotV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
 export interface ReportingLedgerConsumerStatusV1 {
     consumerStatusId: string;
@@ -761,12 +776,34 @@ export interface ReportingLedgerStore {
     }>;
     /** Returns an exact row-bearing revision only when it belongs to the resolved account. */
     getRevision(reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionV1 | null>;
+    /**
+     * Optional row-free counterpart of `getRevision`, scoped to the resolved
+     * account. Exact-read handlers prefer it so they never load every row to
+     * serve one page.
+     */
+    getRevisionMetadata?(reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+    /**
+     * Optional: one page of a revision's rows in ordinal order, only when the
+     * revision belongs to the resolved account. `total` is the revision's row
+     * count. Stores that keep rows outside the revision document verify every
+     * row they return against the committed binding before returning it.
+     */
+    readRevisionRows?(input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;
     listRevisions(reporting_obligation_id: string): Promise<ReportingLedgerRevisionV1[]>;
+    /**
+     * Optional: every retained revision for one obligation without
+     * materializing rows. The producer, lifecycle reconciler and status ingest
+     * prefer it and otherwise fall back to `listRevisions` with rows dropped.
+     * When `account_id` is supplied, only that account's revisions are returned.
+     */
+    listRevisionMetadata?(reporting_obligation_id: string, account_id?: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
     commitAdjustment(adjustment: ReportingLedgerAdjustmentV1, lease: ReportingLedgerLeaseV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerAdjustmentV1;
     }>;
     listAdjustments(reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentV1[]>;
+    /** Optional row-free counterpart of `listAdjustments`, preferred when present. */
+    listAdjustmentMetadata?(reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
     putConsumerStatus(status: ReportingLedgerConsumerStatusV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerConsumerStatusV1;

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-08T17:15:08.701Z"
+  "synced_at": "2026-10-08T19:53:54.089Z"
 }

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.2.2";
+export declare const RUNNER_CAPABILITY_VERSION = "15.4.0";
 /** 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.2.2";
+export declare const RUNNER_CAPABILITY_VERSION = "15.4.0";
 /** 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.2.2";
+export declare const LIBRARY_VERSION = "15.4.0";
 /**
  * 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.2.2";
+    readonly library: "15.4.0";
     readonly adcp: "3.2.3";
     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"];
-    readonly generatedAt: "2026-10-08T16:05:52.268Z";
+    readonly generatedAt: "2026-10-08T17:53:59.048Z";
 };
 /**
  * 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.2.2";
+export declare const LIBRARY_VERSION = "15.4.0";
 /**
  * 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.2.2";
+    readonly library: "15.4.0";
     readonly adcp: "3.2.3";
     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"];
-    readonly generatedAt: "2026-10-08T16:05:52.268Z";
+    readonly generatedAt: "2026-10-08T17:53:59.048Z";
 };
 /**
  * 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.2.2";
+const LIBRARY_VERSION = "15.4.0";
 const ADCP_VERSION = "3.2.3";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -97,10 +97,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.3"
 ];
 const VERSION_INFO = {
-  library: "15.2.2",
+  library: "15.4.0",
   adcp: "3.2.3",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-08T16:05:52.268Z"
+  generatedAt: "2026-10-08T17:53:59.048Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "15.2.2";
+const LIBRARY_VERSION = "15.4.0";
 const ADCP_VERSION = "3.2.3";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -64,10 +64,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.3"
 ];
 const VERSION_INFO = {
-  library: "15.2.2",
+  library: "15.4.0",
   adcp: "3.2.3",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-08T16:05:52.268Z"
+  generatedAt: "2026-10-08T17:53:59.048Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
 > Generated at: 2026-10-08
-> @adcp/sdk v15.2.2
+> @adcp/sdk v15.4.0
 
 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`.
 
@@ -57,6 +57,7 @@ interface TransportOptions {
 }
 
 interface TaskOptions {
+  skipStatusHandlers?: boolean; // Skip inline completion handlers, including continuations
   timeout?: number;             // Absolute whole-task deadline
   signal?: AbortSignal;         // Caller cancellation
   // Direct A2A mutation route, bound to authenticated principal + account scope.

package/docs/guides/PUSH-NOTIFICATION-CONFIG.md

@@ -39,6 +39,45 @@ the reporting webhook schema. A caller-provided reporting URL must always bring
 its own complete authentication block; the client never pairs `webhookSecret`
 with a caller-controlled endpoint.
 
+## Inline completion handlers
+
+Configured status handlers also run inline when a task call returns a successful
+completed result. By default, an inline handler error rejects that call. For a
+forwarding call whose caller will process the returned result, skip the inline
+handler for that call:
+
+```typescript
+const result = await agent.syncCreatives(params, undefined, { skipStatusHandlers: true });
+```
+
+The option follows submitted waits and deferred resumes, including stored
+continuations resumed after restart. Independently delivered webhook handlers
+still run; `skipStatusHandlers` does not disable webhook registration or delivery.
+
+To keep successful results when inline post-processing fails, opt in at client
+construction:
+
+```typescript
+const agent = new SingleAgentClient(sellerConfig, {
+  handlers: {
+    onSyncCreativesStatusChange: recordCreativeResults,
+  },
+  isolateStatusHandlerErrors: true,
+  onStatusHandlerError: async (error, { handlerName, metadata }) => {
+    await recordLocalFailure(error, handlerName, metadata.task_id);
+  },
+});
+```
+
+Isolation returns the completed `TaskResult` and allows settlement acknowledgement.
+The SDK adds a warning to `debug_logs` without including the handler's error text.
+The observer receives the original error and completion metadata, so keep secrets
+out of application logs. Observer errors add a warning and do not reject the task.
+The observer is awaited; keep its work bounded so it cannot stall local completion.
+Cancellation, response validation, settlement acknowledgement errors, and webhook
+error handling retain their existing behavior. With isolation disabled, durable
+handler failures remain retryable without redispatching the seller operation.
+
 ## Wire Payload
 
 The default RFC 9421 registration has no `authentication` block:

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
 > Generated at: 2026-10-08
-> Library: @adcp/sdk v15.2.2
+> Library: @adcp/sdk v15.4.0
 > 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.2.2` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.2.2 dist.integrity` |
+| Exact npm package | `@adcp/sdk@15.4.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.4.0 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.3` |
 | 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` |
@@ -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.2.2'
-npm view '@adcp/sdk@15.2.2' dist.integrity
+npm install --save-exact '@adcp/sdk@15.4.0'
+npm view '@adcp/sdk@15.4.0' dist.integrity
 ```
 
 ### Required and optional peers

package/package.json

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