@adcp/sdk 15.3.0 → 15.5.0

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

@@ -0,0 +1,355 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var row_encoding_exports = {};
+__export(row_encoding_exports, {
+  REPORTING_ROW_CHUNK_MAX_BYTES: () => REPORTING_ROW_CHUNK_MAX_BYTES,
+  REPORTING_ROW_CHUNK_MAX_ROWS: () => REPORTING_ROW_CHUNK_MAX_ROWS,
+  REPORTING_ROW_CHUNK_MAX_SEGMENTS: () => REPORTING_ROW_CHUNK_MAX_SEGMENTS,
+  REPORTING_ROW_ENCODING_V1: () => REPORTING_ROW_ENCODING_V1,
+  REPORTING_ROW_SEGMENT_MAX_ROWS: () => REPORTING_ROW_SEGMENT_MAX_ROWS,
+  ReportingRowEncodingError: () => ReportingRowEncodingError,
+  assertReportingRevisionEnvelopeV1: () => assertReportingRevisionEnvelopeV1,
+  canonicalReportingRowV1: () => canonicalReportingRowV1,
+  createReportingRevisionEnvelopeHasherV1: () => createReportingRevisionEnvelopeHasherV1,
+  createReportingRowsOnlyHasherV1: () => createReportingRowsOnlyHasherV1,
+  decodeVerifiedReportingRowSegmentsV1: () => decodeVerifiedReportingRowSegmentsV1,
+  encodeReportingRowsV1: () => encodeReportingRowsV1,
+  isReportingRowEncodingError: () => isReportingRowEncodingError,
+  reportingRevisionEnvelopeDigestV1: () => reportingRevisionEnvelopeDigestV1,
+  reportingRowManifestSha256V1: () => reportingRowManifestSha256V1,
+  verifyReportingRowChunkV1: () => verifyReportingRowChunkV1,
+  verifyReportingRowManifestsV1: () => verifyReportingRowManifestsV1
+});
+module.exports = __toCommonJS(row_encoding_exports);
+var import_crypto = require("crypto");
+var import_jcs = require('../../utils/jcs.js');
+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 = (0, import_jcs.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(
+    (0, import_jcs.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":${(0, import_jcs.canonicalize)(envelope.control_totals)},"reporting_revision_id":${(0, import_jcs.canonicalize)(
+      envelope.reporting_revision_id
+    )},"reporting_rows":[`,
+    "utf8"
+  );
+  const suffix = Buffer.from(`],"row_count":${(0, import_jcs.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 = (0, import_crypto.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 (0, import_crypto.createHash)("sha256").update(value).digest("hex");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  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/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/row-storage-errors.d.mts

@@ -0,0 +1,7 @@
+export type ReportingRowStoreErrorCode = 'INVALID_INPUT' | 'CONTENT_CONFLICT' | 'ROWS_INTEGRITY_FAILED' | 'ROWS_UNAVAILABLE' | 'ROWS_EXPIRED' | 'PROVIDER_UNAVAILABLE' | 'DEADLINE_EXCEEDED' | 'ABORTED' | 'UNSAFE_BINDING' | 'STATE_UNAVAILABLE';
+/** Stable, secret-free row-storage failure. Switch on `code`. */
+export declare class ReportingRowStoreError extends Error {
+    readonly code: ReportingRowStoreErrorCode;
+    constructor(code: ReportingRowStoreErrorCode, detail?: string);
+}
+export declare function isReportingRowStoreError(error: unknown): error is ReportingRowStoreError;

package/dist/lib/reporting/ledger/row-storage-errors.d.ts

@@ -0,0 +1,7 @@
+export type ReportingRowStoreErrorCode = 'INVALID_INPUT' | 'CONTENT_CONFLICT' | 'ROWS_INTEGRITY_FAILED' | 'ROWS_UNAVAILABLE' | 'ROWS_EXPIRED' | 'PROVIDER_UNAVAILABLE' | 'DEADLINE_EXCEEDED' | 'ABORTED' | 'UNSAFE_BINDING' | 'STATE_UNAVAILABLE';
+/** Stable, secret-free row-storage failure. Switch on `code`. */
+export declare class ReportingRowStoreError extends Error {
+    readonly code: ReportingRowStoreErrorCode;
+    constructor(code: ReportingRowStoreErrorCode, detail?: string);
+}
+export declare function isReportingRowStoreError(error: unknown): error is ReportingRowStoreError;