@adcp/reporting-storage 0.0.0-stage → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 AgenticAdvertising.Org
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @adcp/reporting-storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Storage for AdCP Reliable Reporting. It holds the implementations that sit behind the protocol layer in
+[`@adcp/sdk`](https://www.npmjs.com/package/@adcp/sdk): the PostgreSQL ledger store, revision row storage with GCS, S3
+and Azure Blob providers, managed delivery, notification activity, the BigQuery warehouse sink, and the production
+composition that wires them together.
+
+This package is **pre-1.0 and every export is `@experimental`**: breaking changes ship in minor releases, announced in
+the changelog with a migration note. Pin it with `~` (`~0.1.0-beta.0` while in beta, `~0.1.0` after a stable release). See the
+[stability policy](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md).
+
+## Install
+
+```bash
+# While SDK 16 is in beta, both packages come from the `beta` dist-tag. Drop `@beta` once stable releases exist.
+npm install @adcp/sdk@beta @adcp/reporting-storage@beta pg
+```
+
+`@adcp/sdk` is a **peer dependency** (the SDK 16 line). The store, its errors and the protocol handlers share types and
+symbol-keyed guards, so the host must have exactly one copy of it. Install the pair that was published together: each
+release raises the peer floor to the SDK it was built against. The cloud SDKs are optional peers: install only the
+ones you use.
+
+| You use                    | Also install                    |
+| -------------------------- | ------------------------------- |
+| `@adcp/reporting-storage/gcs`    | `@google-cloud/storage` (`^7.22.0 \|\| ^8.2.0`) |
+| `@adcp/reporting-storage/s3`     | `@aws-sdk/client-s3` (`^3.700.0`) |
+| `@adcp/reporting-storage/azure`  | `@azure/storage-blob` (`^12.23.0`) |
+| `@adcp/reporting-storage/bigquery` | `@google-cloud/bigquery` (you pass the client in) |
+
+## Subpaths
+
+| Import                                | What it holds                                                                                                  |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `@adcp/reporting-storage`             | `PostgresReportingLedgerStore` and its migrations, row storage, object writes, the host change feed, maintenance |
+| `@adcp/reporting-storage/managed`     | managed-delivery runtime, `PostgresReportingManagedDeliveryStore`, the adapter contract and router             |
+| `@adcp/reporting-storage/notifications` | notification activity stores, checkpoints and runtime                                                        |
+| `@adcp/reporting-storage/service`     | `createPostgresReliableReportingProductionService`                                                             |
+| `@adcp/reporting-storage/gcs`         | GCS fence, reader, managed-delivery adapter and row-object provider                                            |
+| `@adcp/reporting-storage/s3`          | S3 row-object provider                                                                                         |
+| `@adcp/reporting-storage/azure`       | Azure Blob row-object provider                                                                                 |
+| `@adcp/reporting-storage/bigquery`    | BigQuery warehouse sink                                                                                        |
+
+The protocol layer stays in `@adcp/sdk`: the `ReportingLedgerStore` interface, the protocol handlers, the producer,
+`createReliableReportingService`, row encoding and digests, `@adcp/sdk/reporting/consumer` and `@adcp/sdk/reporting/source`.
+
+## Apply migrations in this order
+
+Migrations are idempotent SQL strings. Apply them to the ledger database with your migration tool, in this order, and
+only the ones whose feature you turn on.
+
+| Order | Constant                                                | Import                                  | Needed for                              |
+| ----- | ------------------------------------------------------- | --------------------------------------- | --------------------------------------- |
+| 1     | `REPORTING_LEDGER_MIGRATION`                            | `@adcp/reporting-storage`               | always                                  |
+| 2     | `REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION`      | `@adcp/reporting-storage`               | the finality writer fence               |
+| 3     | `REPORTING_ROW_STORAGE_MIGRATION`                       | `@adcp/reporting-storage`               | `rowStorage` (PostgreSQL 13+)           |
+| 4     | `REPORTING_LEDGER_CHANGES_MIGRATION`                    | `@adcp/reporting-storage`               | `changeFeed: true` (PostgreSQL 13+)     |
+| 5     | `REPORTING_MANAGED_DELIVERY_MIGRATION`                  | `@adcp/reporting-storage/managed`       | managed delivery                        |
+| 6     | `REPORTING_OBJECT_WRITE_MIGRATION`, `REPORTING_OBJECT_WRITE_AUTHORITY_MIGRATION` | `@adcp/reporting-storage` | the GCS write fence                     |
+| 7     | `REPORTING_NOTIFICATION_ACTIVITY_MIGRATION`             | `@adcp/reporting-storage/notifications` | notification activity                   |
+| 8     | `REPORTING_WAREHOUSE_SINK_MIGRATION`                    | `@adcp/reporting-storage/bigquery`      | the BigQuery sink (after the change feed) |
+
+`createPostgresReliableReportingProductionService` returns the ordered list it needs as `service.setup.migrations`, and
+`applyMigrations` bridges it into your runner.
+
+## Which import?
+
+| You want                                                        | Import from                                |
+| --------------------------------------------------------------- | ------------------------------------------ |
+| The Core service (`createReliableReportingService`)             | `@adcp/sdk/reporting/service`              |
+| The whole seller chain on PostgreSQL (`createPostgresReliableReportingProductionService`) | `@adcp/reporting-storage/service` |
+| The protocol handlers, producer and the `ReportingLedgerStore` interface | `@adcp/sdk/reporting/ledger` |
+| The PostgreSQL ledger store and the `maintenance` factory       | `@adcp/reporting-storage`                  |
+
+## Use
+
+```ts
+import { Pool } from 'pg';
+import { createReliableReportingService } from '@adcp/sdk/reporting/service';
+import { PostgresReportingLedgerStore, REPORTING_LEDGER_MIGRATION, reportingLedgerMaintenance } from '@adcp/reporting-storage';
+
+const pool = new Pool({ connectionString: process.env.REPORTING_LEDGER_URL });
+await pool.query(REPORTING_LEDGER_MIGRATION);
+
+const store = new PostgresReportingLedgerStore(pool, { acknowledgeIsolatedDatabase: true });
+const reporting = createReliableReportingService({
+  store,
+  // ...adapters, contact, retention commitments, resolvers
+  maintenance: reportingLedgerMaintenance({ retention: { enabled: true } }),
+});
+```
+
+For the full chain (managed delivery, notifications, one scheduler) use `createPostgresReliableReportingProductionService`
+from `@adcp/reporting-storage/service`.
+
+- [Seller reporting ledger](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-LEDGER.md)
+- [Production operations](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-OPERATIONS.md)
+- [Migrating from `@adcp/sdk/reporting/*`](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-reporting-storage-package.md)

package/dist/azure/index.d.mts

@@ -0,0 +1,31 @@
+import type { BlobServiceClient } from '@azure/storage-blob';
+import type { ReportingRowObjectProviderV1 } from '../row-storage-object.mjs';
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
+export interface CreateAzureBlobReportingRowObjectProviderOptionsV1 {
+    /** Official client used by bindings without a `credentialRef`. */
+    client?: BlobServiceClient;
+    /**
+     * Official clients keyed by `credentialRef`. This map is the closed set of
+     * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
+     * Endpoint and credentials come only from these clients.
+     */
+    clients?: Readonly<Record<string, BlobServiceClient>>;
+}
+/**
+ * Azure Blob Storage row-object provider (`@adcp/reporting-storage/azure`).
+ *
+ * Inject official `BlobServiceClient`s with host-owned credentials (managed
+ * identity, workload identity). Bindings use `location: { account, container }`;
+ * the selected client must belong to `account`. Writes are block-blob uploads
+ * with `If-None-Match: *`. Blob versioning must be enabled on the storage account:
+ * the recorded native version is the write-unique `versionId` and pins every read
+ * and delete, so a delayed delete can never remove a later write that re-created
+ * identical bytes at the same key (ETags are content-derived and cannot fence that).
+ * The probe refuses accounts without versioning and proves create-only behaviour
+ * empirically.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
+export declare function createAzureBlobReportingRowObjectProviderV1(options: CreateAzureBlobReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

package/dist/azure/index.d.ts

@@ -0,0 +1,31 @@
+import type { BlobServiceClient } from '@azure/storage-blob';
+import type { ReportingRowObjectProviderV1 } from '../row-storage-object';
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
+export interface CreateAzureBlobReportingRowObjectProviderOptionsV1 {
+    /** Official client used by bindings without a `credentialRef`. */
+    client?: BlobServiceClient;
+    /**
+     * Official clients keyed by `credentialRef`. This map is the closed set of
+     * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
+     * Endpoint and credentials come only from these clients.
+     */
+    clients?: Readonly<Record<string, BlobServiceClient>>;
+}
+/**
+ * Azure Blob Storage row-object provider (`@adcp/reporting-storage/azure`).
+ *
+ * Inject official `BlobServiceClient`s with host-owned credentials (managed
+ * identity, workload identity). Bindings use `location: { account, container }`;
+ * the selected client must belong to `account`. Writes are block-blob uploads
+ * with `If-None-Match: *`. Blob versioning must be enabled on the storage account:
+ * the recorded native version is the write-unique `versionId` and pins every read
+ * and delete, so a delayed delete can never remove a later write that re-created
+ * identical bytes at the same key (ETags are content-derived and cannot fence that).
+ * The probe refuses accounts without versioning and proves create-only behaviour
+ * empirically.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
+export declare function createAzureBlobReportingRowObjectProviderV1(options: CreateAzureBlobReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

package/dist/azure/index.js

@@ -0,0 +1,308 @@
+"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 azure_exports = {};
+__export(azure_exports, {
+  createAzureBlobReportingRowObjectProviderV1: () => createAzureBlobReportingRowObjectProviderV1
+});
+module.exports = __toCommonJS(azure_exports);
+var import_node_crypto = require("node:crypto");
+var import_ledger = require("@adcp/sdk/reporting/ledger");
+var import_row_storage_provider_io = require('../row-storage-provider-io.js');
+const ACCOUNT = /^[a-z0-9]{3,24}$/;
+const CONTAINER = /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){2,62}$/;
+const VERSION_ID = /^[0-9A-Za-z:.+-]{1,64}$/;
+function statusOf(error) {
+  const status = Number(error?.statusCode);
+  return Number.isInteger(status) ? status : void 0;
+}
+function codeOf(error) {
+  const value = error?.code ?? error?.details?.errorCode;
+  return typeof value === "string" ? value : "";
+}
+const isConflict = (error) => statusOf(error) === 409 || statusOf(error) === 412 || codeOf(error) === "BlobAlreadyExists";
+const isMissing = (error) => statusOf(error) === 404 || statusOf(error) === 412;
+const isForbidden = (error) => statusOf(error) === 401 || statusOf(error) === 403;
+function versionOf(response) {
+  const id = response.versionId;
+  if (typeof id !== "string" || !VERSION_ID.test(id)) {
+    throw new import_ledger.ReportingRowStoreError(
+      "UNSAFE_BINDING",
+      "store returned no blob versionId; blob versioning must be enabled on the storage account so deletes are fenced to one write"
+    );
+  }
+  return id;
+}
+function servedVersion(response, versionId) {
+  return response.versionId === versionId;
+}
+function metadataOf(metadata) {
+  const result = {};
+  for (const [name, value] of Object.entries(metadata)) {
+    const identifier = name.replace(/[^A-Za-z0-9_]/g, "_");
+    result[/^[A-Za-z_]/.test(identifier) ? identifier : `_${identifier}`] = value;
+  }
+  return result;
+}
+function createAzureBlobReportingRowObjectProviderV1(options) {
+  if (!options || typeof options !== "object") {
+    throw new import_ledger.ReportingRowStoreError("INVALID_INPUT", "Azure Blob row provider options are required");
+  }
+  const clients = (0, import_row_storage_provider_io.reportingRowClientMap)(options.clients);
+  const isClient = (value) => !!value && typeof value === "object" && typeof value.getContainerClient === "function" && typeof value.accountName === "string";
+  if (options.client !== void 0 && !isClient(options.client) || [...clients.values()].some((client) => !isClient(client)) || options.client === void 0 && clients.size === 0) {
+    throw new import_ledger.ReportingRowStoreError("INVALID_INPUT", "inject an official BlobServiceClient as client or clients");
+  }
+  const validateLocation = (location) => {
+    (0, import_row_storage_provider_io.assertReportingRowLocationKeys)(location, ["account", "container"]);
+    if (!ACCOUNT.test(location.account)) {
+      throw new import_ledger.ReportingRowStoreError("INVALID_INPUT", "Azure storage account name is invalid");
+    }
+    if (!CONTAINER.test(location.container)) {
+      throw new import_ledger.ReportingRowStoreError("INVALID_INPUT", "Azure container name is invalid");
+    }
+  };
+  const containerFor = (input) => {
+    validateLocation(input.location);
+    const client = (0, import_row_storage_provider_io.selectReportingRowClient)(options.client, clients, input.credentialRef);
+    if (client.accountName !== input.location.account) {
+      throw new import_ledger.ReportingRowStoreError("UNSAFE_BINDING", "client does not belong to the binding account");
+    }
+    return client.getContainerClient(input.location.container);
+  };
+  const blobFor = (input) => {
+    if (typeof input.objectRef !== "string" || input.objectRef.length === 0 || input.objectRef.length > 1024) {
+      throw new import_ledger.ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
+    }
+    return containerFor(input).getBlockBlobClient(input.objectRef);
+  };
+  const pinned = (blob, nativeVersionRef) => typeof nativeVersionRef === "string" && VERSION_ID.test(nativeVersionRef) ? { blob: blob.withVersion(nativeVersionRef), versionId: nativeVersionRef } : null;
+  async function assertCreateOnlyEnforced(container, prefix, signal) {
+    const blob = container.getBlockBlobClient(`${prefix}/.adcp-probe/${(0, import_node_crypto.randomUUID)()}`);
+    const versionIds = [];
+    let written = false;
+    const upload = async (body) => {
+      const bytes = Buffer.from(body);
+      const response = await blob.upload(bytes, bytes.byteLength, {
+        conditions: { ifNoneMatch: "*" },
+        blobHTTPHeaders: { blobContentType: "application/x-ndjson", blobCacheControl: "no-store" },
+        abortSignal: signal
+      });
+      written = true;
+      if (response.versionId) versionIds.push(response.versionId);
+      versionOf(response);
+    };
+    try {
+      await upload('{"probe":1}\n');
+      try {
+        await upload('{"probe":2}\n');
+      } catch (error) {
+        if (isConflict(error)) return;
+        throw error;
+      }
+      throw new import_ledger.ReportingRowStoreError("UNSAFE_BINDING", "store ignores If-None-Match and replaces blobs");
+    } finally {
+      if (written && !signal.aborted) {
+        await blob.delete({ abortSignal: signal }).catch(() => void 0);
+        for (const versionId of versionIds) {
+          if (signal.aborted) break;
+          await blob.withVersion(versionId).delete({ abortSignal: signal }).catch(() => void 0);
+        }
+      }
+    }
+  }
+  return {
+    name: "azure_blob",
+    rangedReads: true,
+    validateLocation,
+    probe(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const container = containerFor(input);
+        let properties;
+        try {
+          properties = await container.getProperties({ abortSignal: context.signal });
+        } catch (error) {
+          if (statusOf(error) === 404) throw new import_ledger.ReportingRowStoreError("UNSAFE_BINDING", "container does not exist");
+          if (isForbidden(error)) throw new import_ledger.ReportingRowStoreError("UNSAFE_BINDING", "container is not accessible");
+          throw error;
+        }
+        if (properties.blobPublicAccess) {
+          throw new import_ledger.ReportingRowStoreError("UNSAFE_BINDING", "container allows anonymous read access");
+        }
+        await assertCreateOnlyEnforced(container, input.prefix, context.signal);
+      });
+    },
+    putIfAbsent(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const blob = blobFor(input);
+        const bytes = Buffer.from(input.bytes);
+        try {
+          const response = await blob.upload(bytes, bytes.byteLength, {
+            conditions: { ifNoneMatch: "*" },
+            blobHTTPHeaders: { blobContentType: input.contentType, blobCacheControl: "no-store" },
+            metadata: metadataOf(input.metadata),
+            abortSignal: context.signal
+          });
+          return { created: true, nativeVersionRef: versionOf(response) };
+        } catch (error) {
+          if (!isConflict(error)) throw error;
+        }
+        const existing = await blob.getProperties({ abortSignal: context.signal });
+        return { created: false, nativeVersionRef: versionOf(existing) };
+      });
+    },
+    get(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const blob = blobFor(input);
+        (0, import_row_storage_provider_io.assertReportingRowReadBounds)(input);
+        const target = pinned(blob, input.nativeVersionRef);
+        if (target === null) return null;
+        try {
+          if (input.range?.length === 0) {
+            const properties = await target.blob.getProperties({ abortSignal: context.signal });
+            if (!servedVersion(properties, target.versionId)) return null;
+            if (input.range.offset > Number(properties.contentLength ?? 0)) {
+              throw new import_ledger.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+            }
+            return Buffer.alloc(0);
+          }
+          const response = await target.blob.download(input.range?.offset ?? 0, input.range?.length, {
+            abortSignal: context.signal
+          });
+          const body = response.readableStreamBody;
+          if (!body || typeof body[Symbol.asyncIterator] !== "function") {
+            throw new import_ledger.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "blob body is not a stream");
+          }
+          if (!servedVersion(response, target.versionId)) {
+            body.destroy?.();
+            return null;
+          }
+          if (typeof response.contentLength === "number" && response.contentLength > input.maxBytes) {
+            body.destroy?.();
+            throw new import_ledger.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
+          }
+          return await (0, import_row_storage_provider_io.readReportingRowStream)(body, input.maxBytes, context.signal);
+        } catch (error) {
+          if (isMissing(error)) return null;
+          if (statusOf(error) === 400) return null;
+          if (statusOf(error) === 416 || codeOf(error) === "InvalidRange") {
+            throw new import_ledger.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+          }
+          throw error;
+        }
+      });
+    },
+    stat(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const blob = blobFor(input);
+        const target = pinned(blob, input.nativeVersionRef);
+        if (target === null) return null;
+        try {
+          const properties = await target.blob.getProperties({ abortSignal: context.signal });
+          if (!servedVersion(properties, target.versionId)) return null;
+          const size = properties.contentLength;
+          if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) {
+            throw new import_ledger.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "blob metadata is malformed");
+          }
+          return { nativeVersionRef: target.versionId, sizeBytes: size };
+        } catch (error) {
+          if (isMissing(error) || statusOf(error) === 400) return null;
+          throw error;
+        }
+      });
+    },
+    list(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const container = containerFor(input);
+        if (typeof input.prefix !== "string" || input.prefix.length > 1024) {
+          throw new import_ledger.ReportingRowStoreError("INVALID_INPUT", "list prefix is invalid");
+        }
+        if (!Number.isSafeInteger(input.pageSize) || input.pageSize < 1) {
+          throw new import_ledger.ReportingRowStoreError("INVALID_INPUT", "pageSize must be a positive integer");
+        }
+        const pages = container.listBlobsFlat({ prefix: input.prefix, includeVersions: true, abortSignal: context.signal }).byPage({
+          maxPageSize: Math.min(input.pageSize, 5e3),
+          ...input.pageToken ? { continuationToken: input.pageToken } : {}
+        });
+        const page = (await pages.next()).value;
+        const objects = [];
+        let skipped = 0;
+        for (const item of page?.segment?.blobItems ?? []) {
+          const size = item.properties?.contentLength;
+          const created = Math.max(
+            item.properties?.createdOn?.getTime() ?? NaN,
+            item.properties?.lastModified?.getTime() ?? 0
+          );
+          if (typeof item.name !== "string" || !item.name.startsWith(input.prefix) || typeof item.versionId !== "string" || !VERSION_ID.test(item.versionId) || typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || !Number.isFinite(created)) {
+            skipped += 1;
+            continue;
+          }
+          objects.push({
+            objectRef: item.name,
+            nativeVersionRef: item.versionId,
+            sizeBytes: size,
+            createdAt: new Date(created).toISOString()
+          });
+        }
+        await pages.return?.(void 0);
+        const token = page?.continuationToken;
+        return {
+          objects,
+          ...skipped > 0 ? { skipped } : {},
+          ...typeof token === "string" && token ? { nextPageToken: token } : {}
+        };
+      });
+    },
+    delete(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const blob = blobFor(input);
+        const target = pinned(blob, input.nativeVersionRef);
+        if (target === null) return "absent";
+        const signal = context.signal;
+        try {
+          const recorded = await target.blob.getProperties({ abortSignal: signal });
+          if (recorded.versionId !== target.versionId) return "absent";
+        } catch (error) {
+          if (isMissing(error) || statusOf(error) === 400) return "absent";
+          throw error;
+        }
+        let deletedCurrent = false;
+        try {
+          const current = await blob.getProperties({ abortSignal: signal });
+          if (current.versionId === target.versionId && current.etag) {
+            await blob.delete({ conditions: { ifMatch: current.etag }, abortSignal: signal });
+            deletedCurrent = true;
+          }
+        } catch (error) {
+          if (!isMissing(error)) throw error;
+        }
+        try {
+          await target.blob.delete({ abortSignal: signal });
+          return "deleted";
+        } catch (error) {
+          if (isMissing(error) || statusOf(error) === 400) return deletedCurrent ? "deleted" : "absent";
+          throw error;
+        }
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAzureBlobReportingRowObjectProviderV1
+});