@cloudbitmaps/s3 0.10.0-rc.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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/NOTICE

@@ -0,0 +1,11 @@
+@cloudbitmaps/s3
+Copyright 2026 Sharvil Kadam
+
+This product includes software developed as an open-source project.
+Licensed under the Apache License, Version 2.0 (the "License"); see the LICENSE
+file. You may obtain a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+@cloudbitmaps/s3 is a storage driver for CloudBitmaps. It contains no bitmap code and is
+codec-agnostic: it moves opaque payload bytes.

package/README.md

@@ -0,0 +1,76 @@
+# @cloudbitmaps/s3
+
+**S3 and S3-compatible object storage for [CloudBitmaps](https://github.com/cloudbitmaps/cloudbitmaps).**
+
+> **ESM-only, Node ≥ 22.12.** This package ships as ES modules; there is no CommonJS bundle.
+> `require()` works on Node 22.12+ through `require(esm)`, but a runner with its own CommonJS loader
+> (notably Jest in its default configuration) does not get that and needs `import` instead. On TypeScript,
+> a CommonJS project needs `"module": "nodenext"` or `"node20"`. See the
+> [repository README](https://github.com/cloudbitmaps/cloudbitmaps#install--entry-points) for the details.
+
+AWS S3 — and every S3-compatible service: Cloudflare R2, MinIO, Ceph, Wasabi, Backblaze B2.
+
+## Install
+
+```bash
+pnpm add @cloudbitmaps/roaring @cloudbitmaps/s3
+# npm i @cloudbitmaps/roaring @cloudbitmaps/s3   # the same, with npm
+```
+
+> **On pnpm 10+, allow the one build script.** pnpm 10 skips dependency build scripts by default, so
+> the `roaring` native addon never downloads and the package throws at `import` — while the install
+> itself prints a warning and **exits 0**. Add this to your `package.json`, then install:
+>
+> ```json
+> { "pnpm": { "onlyBuiltDependencies": ["roaring"] } }
+> ```
+>
+> pnpm 9 and npm run it already. [Full symptoms and fixes](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#cannot-find-module-buildreleaseroaringnode-after-a-successful-install).
+
+Two packages: the **codec** you want and the **storage** you have. `@aws-sdk/client-s3` (`>=3.645.0 <4`) is a real dependency of
+this package, so installing it is the whole step — there is no optional peer to remember. `@cloudbitmaps/core` is one
+too, so the engine lands in your tree without you installing it — you never name it yourself.
+
+> **The `>=3.645.0` floor is a correctness floor, not a preference.** Below it the SDK does not model the
+> conditional write this library's write-once guarantee is built on: measured against MinIO, **3.640.0
+> silently overwrites** an existing object instead of refusing, which loses a published generation without
+> an error; 3.641.0 rejects correctly. If you pin `@aws-sdk/client-s3` yourself, raise the pin to at least
+> `3.645.0` — an older pin will fail to resolve against this package rather than quietly downgrading you.
+
+## Use
+
+```ts
+import { CloudRoaring } from '@cloudbitmaps/roaring';
+import { S3Storage } from '@cloudbitmaps/s3';
+
+const store = new CloudRoaring({
+  storage: new S3Storage({ bucket: 'bitmaps', prefix: 'cr', region: 'us-east-1' }),
+});
+
+await store.load({ segment: 'active-users' }, [1, 2, 3]);
+const seg = store.segment('active-users');
+await seg.has(2); // true
+```
+
+`S3Storage` configures both halves — the immutable generation objects and the registry pointer row — from one set
+of values. Need them apart? This package also exports the two drivers and their option types; see the
+[API reference](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md).
+
+## What this package is
+
+These drivers move opaque payload bytes, so they are codec-agnostic: the same package serves every codec
+flavor. That is why storage is a package rather than a subpath of one — as a subpath, each flavor needed a
+re-export barrel per service, and the count multiplied with every codec added.
+
+Built against `@cloudbitmaps/core/driver-kit`, the declared contract for a driver — the same surface a
+third-party driver would use.
+
+## Documentation
+
+- [Getting started](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md)
+- [API reference](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md)
+- [Changelog](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/CHANGELOG.md)
+
+## License
+
+Apache-2.0

package/dist/backend.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `S3Storage` — the S3 backend as one object: the generations and the pointer, in one bucket, stated once.
+ *
+ * Replaces two constructor calls that each repeated `client`, `bucket` and `prefix`. Repeating them is how
+ * they come apart: point the registry at one prefix and the objects at another and the store answers *empty*
+ * rather than *misconfigured*, which is the hardest kind of wrong answer to debug. Here the location is written
+ * once and shared, so the mismatch cannot be expressed.
+ *
+ * **It will build a client for you**, which is the common case — `new S3Storage({ bucket })` picks up the
+ * ambient credential chain and region exactly as the SDK would. Pass `client` instead when you need a
+ * credential chain the SDK cannot infer (SSO, an assumed role, a custom retry strategy); pass `endpoint` +
+ * `pathStyle` + `credentials` for an S3-compatible store (MinIO, Ceph, R2). Both halves stay reachable as `.storage` and
+ * `.registry` for anyone wiring something the facade does not cover.
+ */
+import { STORAGE_BACKEND } from '@cloudbitmaps/core/driver-kit';
+import type { IRegistryDriver, IStorageDriver, StorageBackend } from '@cloudbitmaps/core/driver-kit';
+import { S3Client } from '@aws-sdk/client-s3';
+export interface S3StorageOptions {
+    /** Target bucket (must already exist). */
+    readonly bucket: string;
+    /** Optional key prefix under which everything lives — generations and the registry alike. */
+    readonly prefix?: string;
+    /** A constructed client. Supply one for a credential chain the SDK cannot infer; otherwise one is built. */
+    readonly client?: S3Client;
+    /** Region for the client built when `client` is absent. Falls back to the SDK's own resolution. */
+    readonly region?: string;
+    /** Endpoint for an S3-compatible store (MinIO, Ceph, R2). Ignored when `client` is supplied. */
+    readonly endpoint?: string;
+    /** Path-style addressing, which most S3-compatible stores require. Ignored when `client` is supplied. */
+    readonly pathStyle?: boolean;
+    /**
+     * Static credentials, for the S3-compatible stores that issue them (MinIO, Ceph, R2).
+     *
+     * On AWS itself, leave this unset — the SDK's own chain (instance role, SSO, environment, profile) is what
+     * you want, and hard-coding keys to reach it would be a downgrade. It exists because the alternative for a
+     * MinIO user was to construct an `S3Client` purely to carry two strings, which is the ergonomics this class
+     * is here to remove. Ignored when `client` is supplied.
+     */
+    readonly credentials?: {
+        readonly accessKeyId: string;
+        readonly secretAccessKey: string;
+        readonly sessionToken?: string;
+    };
+    /** Injected clock for the registry's `createdAt`/`updatedAt`; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+export declare class S3Storage implements StorageBackend {
+    /** Cross-bundle brand, stamped non-enumerably in the constructor so a spread cannot carry it. */
+    readonly [STORAGE_BACKEND]: true;
+    readonly storage: IStorageDriver;
+    readonly registry: IRegistryDriver;
+    /** The client both halves share — built here unless one was supplied. */
+    readonly client: S3Client;
+    constructor(options: S3StorageOptions);
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@cloudbitmaps/s3` — S3 and every S3-compatible service — Cloudflare R2, MinIO, Ceph, Wasabi, Backblaze B2.
+ *
+ * One package per storage SERVICE, with `@aws-sdk/client-s3` as a real dependency. Install it alongside a
+ * flavor package and wire the backend in one line:
+ *
+ * ```ts
+ * import { CloudRoaring } from '@cloudbitmaps/roaring';
+ * import { S3Storage } from '@cloudbitmaps/s3';
+ *
+ * const store = new CloudRoaring({ storage: new S3Storage({ bucket: 'bitmaps', prefix: 'cr' }) });
+ * ```
+ *
+ * These drivers move opaque payload bytes, so they are codec-agnostic: the same package serves every
+ * flavor. That is why they are a package rather than a subpath of one — as a subpath, each flavor needed a
+ * re-export barrel per service, and the count multiplied with every new codec.
+ *
+ * The engine, the `.crbm` format and the ports live in `@cloudbitmaps/core`, which is a real dependency of
+ * THIS package: it lands in your tree without you installing it, and you never name it yourself. What this
+ * package builds against is `@cloudbitmaps/core/driver-kit`, the declared contract for a driver — the same
+ * surface a third-party driver would use.
+ */
+export { S3StorageDriver } from './storage.js';
+export type { S3StorageDriverOptions } from './storage.js';
+export { S3RegistryDriver } from './registry.js';
+export type { S3RegistryDriverOptions } from './registry.js';
+export { S3Storage } from './backend.js';
+export type { S3StorageOptions } from './backend.js';

package/dist/index.js

@@ -0,0 +1,508 @@
+// src/storage.ts
+import {
+  NotFoundError,
+  TransientError,
+  ValidationError as ValidationError2,
+  WriteConflictError,
+  isNotFoundError,
+  isValidationError,
+  isWriteConflictError
+} from "@cloudbitmaps/core/driver-kit";
+import { createHash } from "node:crypto";
+import {
+  AbortMultipartUploadCommand,
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  UploadPartCommand
+} from "@aws-sdk/client-s3";
+
+// src/keys.ts
+import {
+  ValidationError,
+  encodeNameForKey,
+  namespaceKeyPart,
+  prefixPart,
+  validateSegmentRef
+} from "@cloudbitmaps/core/driver-kit";
+import { normalizeObjectPrefix } from "@cloudbitmaps/core/driver-kit";
+import {
+  registryPrefix,
+  registryObjectKey,
+  registryListPrefix,
+  parseRegistryKey
+} from "@cloudbitmaps/core/driver-kit";
+var SUFFIX = ".crbm";
+function segmentObjectPrefix(prefix, ref) {
+  validateSegmentRef(ref);
+  return `${prefixPart(prefix)}${namespaceKeyPart(ref.namespace)}/segments/${encodeNameForKey(ref.segment)}.`;
+}
+function storageObjectKey(prefix, key) {
+  if (!Number.isInteger(key.generation) || key.generation < 0) {
+    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);
+  }
+  return `${segmentObjectPrefix(prefix, key)}${key.generation}${SUFFIX}`;
+}
+function parseGenerationFromKey(segmentPrefix, objectKey) {
+  if (!objectKey.startsWith(segmentPrefix) || !objectKey.endsWith(SUFFIX)) return null;
+  const middle = objectKey.slice(segmentPrefix.length, objectKey.length - SUFFIX.length);
+  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
+  const generation = Number(middle);
+  return Number.isSafeInteger(generation) ? generation : null;
+}
+
+// src/s3-errors.ts
+import {
+  errorName,
+  httpStatus,
+  isNetworkOrTimeout,
+  isSdkRetryable,
+  isServerSide
+} from "@cloudbitmaps/core/driver-kit";
+function isPreconditionFailed(err) {
+  return errorName(err) === "PreconditionFailed" || httpStatus(err) === 412;
+}
+function isConditionalConflict(err) {
+  return isPreconditionFailed(err) || errorName(err) === "ConditionalRequestConflict" || httpStatus(err) === 409;
+}
+function isNotFound(err) {
+  const name = errorName(err);
+  return name === "NoSuchKey" || name === "NotFound" || httpStatus(err) === 404;
+}
+function isInvalidRange(err) {
+  return errorName(err) === "InvalidRange" || httpStatus(err) === 416;
+}
+function isTransient(err) {
+  if (isConditionalConflict(err) || isNotFound(err) || isInvalidRange(err)) return false;
+  return errorName(err) === "SlowDown" || isServerSide(err) || isNetworkOrTimeout(err) || isSdkRetryable(err);
+}
+function totalFromContentRange(contentRange) {
+  if (contentRange === void 0) return void 0;
+  const match = /\/(\d+)\s*$/.exec(contentRange);
+  if (match === null) return void 0;
+  const total = Number(match[1]);
+  return Number.isSafeInteger(total) ? total : void 0;
+}
+
+// src/storage.ts
+var S3_PART_BYTES = 8 * 1024 * 1024;
+var S3_MAX_PARTS = 1e4;
+var S3StorageDriver = class {
+  client;
+  bucket;
+  prefix;
+  maxObjectBytes;
+  partBytes;
+  constructor(options) {
+    this.client = options.client;
+    this.bucket = options.bucket;
+    this.prefix = normalizeObjectPrefix(options.prefix);
+    const requestedPart = Math.max(options.partBytes ?? S3_PART_BYTES, 5 * 1024 * 1024);
+    this.maxObjectBytes = options.maxObjectBytes ?? requestedPart * S3_MAX_PARTS;
+    this.partBytes = Math.max(requestedPart, Math.ceil(this.maxObjectBytes / S3_MAX_PARTS));
+  }
+  capabilities() {
+    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
+  }
+  async putImmutable(key, write) {
+    const objectKey = storageObjectKey(this.prefix, key);
+    const sink = new S3MultipartSink(
+      this.client,
+      this.bucket,
+      objectKey,
+      this.partBytes,
+      this.maxObjectBytes
+    );
+    try {
+      await write(sink);
+      return await sink.finish();
+    } catch (err) {
+      await sink.abort();
+      if (isConditionalConflict(err)) {
+        throw new WriteConflictError(
+          `generation already exists (write-once): ${key.segment}.${key.generation}`
+        );
+      }
+      if (isValidationError(err) || isWriteConflictError(err) || isNotFoundError(err)) {
+        throw err;
+      }
+      throw this.mapError(err);
+    }
+  }
+  async getRange(key, offset, length) {
+    if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {
+      throw new ValidationError2(`invalid range offset=${offset} length=${length}`);
+    }
+    const objectKey = storageObjectKey(this.prefix, key);
+    if (length === 0) return new Uint8Array(0);
+    try {
+      const res = await this.client.send(
+        new GetObjectCommand({
+          Bucket: this.bucket,
+          Key: objectKey,
+          Range: `bytes=${offset}-${offset + length - 1}`
+        })
+      );
+      const bytes = await collect(res.Body);
+      if (bytes.length !== length) {
+        throw new ValidationError2(
+          `range [${offset}, ${offset + length}) out of bounds (got ${bytes.length}B)`
+        );
+      }
+      return bytes;
+    } catch (err) {
+      throw this.mapReadError(err, key);
+    }
+  }
+  async getTail(key, maxBytes) {
+    const objectKey = storageObjectKey(this.prefix, key);
+    if (maxBytes <= 0) {
+      try {
+        const head = await this.client.send(
+          new HeadObjectCommand({ Bucket: this.bucket, Key: objectKey })
+        );
+        return { bytes: new Uint8Array(0), size: head.ContentLength ?? 0 };
+      } catch (err) {
+        throw this.mapReadError(err, key);
+      }
+    }
+    try {
+      const res = await this.client.send(
+        new GetObjectCommand({ Bucket: this.bucket, Key: objectKey, Range: `bytes=-${maxBytes}` })
+      );
+      const bytes = await collect(res.Body);
+      let size = totalFromContentRange(res.ContentRange);
+      if (size === void 0) {
+        if (bytes.length === maxBytes) {
+          const head = await this.client.send(
+            new HeadObjectCommand({ Bucket: this.bucket, Key: objectKey })
+          );
+          size = head.ContentLength ?? bytes.length;
+        } else {
+          size = bytes.length;
+        }
+      }
+      return { bytes, size };
+    } catch (err) {
+      throw this.mapReadError(err, key);
+    }
+  }
+  async delete(key) {
+    try {
+      await this.client.send(
+        new DeleteObjectCommand({ Bucket: this.bucket, Key: storageObjectKey(this.prefix, key) })
+      );
+    } catch (err) {
+      throw this.mapError(err);
+    }
+  }
+  async *list(ref) {
+    const prefix = segmentObjectPrefix(this.prefix, ref);
+    let token;
+    do {
+      let res;
+      try {
+        res = await this.client.send(
+          new ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: prefix,
+            ContinuationToken: token
+          })
+        );
+      } catch (err) {
+        throw this.mapError(err);
+      }
+      for (const obj of res.Contents ?? []) {
+        if (obj.Key === void 0) continue;
+        const generation = parseGenerationFromKey(prefix, obj.Key);
+        if (generation !== null) {
+          yield { namespace: ref.namespace, segment: ref.segment, generation };
+        }
+      }
+      token = res.IsTruncated === true ? res.NextContinuationToken : void 0;
+    } while (token !== void 0);
+  }
+  /** Map S3 read errors to the driver vocabulary; pass everything else through {@link mapError}. */
+  mapReadError(err, key) {
+    if (isValidationError(err)) return err;
+    if (isNotFound(err)) {
+      return new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
+    }
+    if (isInvalidRange(err)) {
+      return new ValidationError2(`range out of bounds for ${key.segment}.${key.generation}`);
+    }
+    return this.mapError(err);
+  }
+  /**
+   * Reclassify a transient S3 fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}
+   * so the retry decorator can ride it out; everything else propagates unchanged. The final fallback at every
+   * `client.send` site, so callers and the decorator only ever see typed errors.
+   */
+  mapError(err) {
+    if (isTransient(err)) {
+      return new TransientError(
+        `transient S3 fault: ${err?.name ?? "unknown"}`,
+        { cause: err }
+      );
+    }
+    return err;
+  }
+};
+function concatBytes(parts, total) {
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+var S3MultipartSink = class {
+  constructor(client, bucket, objectKey, partBytes, maxObjectBytes) {
+    this.client = client;
+    this.bucket = bucket;
+    this.objectKey = objectKey;
+    this.partBytes = partBytes;
+    this.maxObjectBytes = maxObjectBytes;
+  }
+  client;
+  bucket;
+  objectKey;
+  partBytes;
+  maxObjectBytes;
+  hash = createHash("sha256");
+  pending = [];
+  pendingLen = 0;
+  total = 0;
+  uploadId;
+  partNumber = 0;
+  parts = [];
+  async write(bytes) {
+    if (bytes.length === 0) return;
+    this.total += bytes.length;
+    if (this.total > this.maxObjectBytes) {
+      throw new ValidationError2(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
+    }
+    this.hash.update(bytes);
+    this.pending.push(bytes);
+    this.pendingLen += bytes.length;
+    if (this.pendingLen >= this.partBytes) await this.flushPart();
+  }
+  /** Upload the buffered bytes (≥ one part) as a single part, freeing them. Starts the upload on first call. */
+  async flushPart() {
+    if (this.uploadId === void 0) {
+      const res2 = await this.client.send(
+        new CreateMultipartUploadCommand({ Bucket: this.bucket, Key: this.objectKey })
+      );
+      if (res2.UploadId === void 0) {
+        throw new TransientError("S3 CreateMultipartUpload returned no UploadId");
+      }
+      this.uploadId = res2.UploadId;
+    }
+    const body = concatBytes(this.pending, this.pendingLen);
+    this.pending.length = 0;
+    this.pendingLen = 0;
+    this.partNumber += 1;
+    if (this.partNumber > S3_MAX_PARTS) {
+      throw new ValidationError2(`multipart upload exceeded the S3 ${S3_MAX_PARTS}-part limit`);
+    }
+    const res = await this.client.send(
+      new UploadPartCommand({
+        Bucket: this.bucket,
+        Key: this.objectKey,
+        UploadId: this.uploadId,
+        PartNumber: this.partNumber,
+        Body: body
+      })
+    );
+    this.parts.push({ ETag: res.ETag, PartNumber: this.partNumber });
+  }
+  /** Commit the object: a single conditional PUT if it fit in one part, else complete the multipart upload. */
+  async finish() {
+    const sha256 = this.hash.digest("hex");
+    if (this.uploadId === void 0) {
+      await this.client.send(
+        new PutObjectCommand({
+          Bucket: this.bucket,
+          Key: this.objectKey,
+          Body: concatBytes(this.pending, this.pendingLen),
+          IfNoneMatch: "*"
+          // write-once
+        })
+      );
+      return { size: this.total, sha256 };
+    }
+    if (this.pendingLen > 0) await this.flushPart();
+    await this.client.send(
+      new CompleteMultipartUploadCommand({
+        Bucket: this.bucket,
+        Key: this.objectKey,
+        UploadId: this.uploadId,
+        MultipartUpload: { Parts: this.parts },
+        IfNoneMatch: "*"
+        // write-once: fail if the object already exists
+      })
+    );
+    this.uploadId = void 0;
+    return { size: this.total, sha256 };
+  }
+  /** Best-effort cleanup of an in-flight multipart upload after an error (a leaked MPU is reaped by a bucket
+   * lifecycle rule; never a correctness issue). No-op if nothing was started or it already completed. */
+  async abort() {
+    if (this.uploadId === void 0) return;
+    const id = this.uploadId;
+    this.uploadId = void 0;
+    try {
+      await this.client.send(
+        new AbortMultipartUploadCommand({ Bucket: this.bucket, Key: this.objectKey, UploadId: id })
+      );
+    } catch {
+    }
+  }
+};
+async function collect(body) {
+  if (body === void 0) {
+    throw new NotFoundError("S3 GetObject returned an empty body");
+  }
+  return body.transformToByteArray();
+}
+
+// src/registry.ts
+import {
+  IntegrityError,
+  MAX_ROW_BYTES,
+  ObjectStoreRegistry,
+  TransientError as TransientError2,
+  WriteConflictError as WriteConflictError2,
+  normalizeObjectPrefix as normalizeObjectPrefix2
+} from "@cloudbitmaps/core/driver-kit";
+import {
+  GetObjectCommand as GetObjectCommand2,
+  ListObjectsV2Command as ListObjectsV2Command2,
+  PutObjectCommand as PutObjectCommand2
+} from "@aws-sdk/client-s3";
+var S3Store = class {
+  constructor(client, bucket) {
+    this.client = client;
+    this.bucket = bucket;
+  }
+  client;
+  bucket;
+  label = "S3";
+  async read(key) {
+    let res;
+    try {
+      res = await this.client.send(new GetObjectCommand2({ Bucket: this.bucket, Key: key }));
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw mapError(err);
+    }
+    if ((res.ContentLength ?? 0) > MAX_ROW_BYTES) {
+      throw new IntegrityError(
+        `registry object ${res.ContentLength}B exceeds cap ${MAX_ROW_BYTES}B`
+      );
+    }
+    if (res.Body === void 0) {
+      throw new IntegrityError(`registry object has an empty body: ${key}`);
+    }
+    const bytes = await res.Body.transformToByteArray();
+    return { bytes, version: res.ETag ?? "" };
+  }
+  async write(key, body, expect) {
+    try {
+      await this.client.send(
+        new PutObjectCommand2({
+          Bucket: this.bucket,
+          Key: key,
+          Body: body,
+          ContentType: "application/json",
+          IfNoneMatch: expect === "absent" ? "*" : void 0,
+          IfMatch: expect === "absent" ? void 0 : expect.version
+        })
+      );
+    } catch (err) {
+      if (isConditionalConflict(err)) {
+        throw new WriteConflictError2(`registry OCC conflict for ${key}`);
+      }
+      throw mapError(err);
+    }
+  }
+  async *listKeys(prefix) {
+    let token;
+    do {
+      let res;
+      try {
+        res = await this.client.send(
+          new ListObjectsV2Command2({
+            Bucket: this.bucket,
+            Prefix: prefix,
+            ContinuationToken: token
+          })
+        );
+      } catch (err) {
+        throw mapError(err);
+      }
+      for (const obj of res.Contents ?? []) {
+        if (obj.Key !== void 0) yield obj.Key;
+      }
+      token = res.IsTruncated === true ? res.NextContinuationToken : void 0;
+    } while (token !== void 0);
+  }
+};
+function mapError(err) {
+  if (isTransient(err)) {
+    return new TransientError2(
+      `transient S3 fault: ${err?.name ?? "unknown"}`,
+      { cause: err }
+    );
+  }
+  return err;
+}
+var S3RegistryDriver = class extends ObjectStoreRegistry {
+  constructor(options) {
+    super(
+      new S3Store(options.client, options.bucket),
+      normalizeObjectPrefix2(options.prefix),
+      options.now ?? (() => Date.now())
+    );
+  }
+};
+
+// src/backend.ts
+import { brandAsBackend } from "@cloudbitmaps/core/driver-kit";
+import { S3Client } from "@aws-sdk/client-s3";
+var S3Storage = class {
+  storage;
+  registry;
+  /** The client both halves share — built here unless one was supplied. */
+  client;
+  constructor(options) {
+    this.client = options.client ?? new S3Client({
+      ...options.region === void 0 ? {} : { region: options.region },
+      ...options.endpoint === void 0 ? {} : { endpoint: options.endpoint },
+      ...options.pathStyle === void 0 ? {} : { forcePathStyle: options.pathStyle },
+      ...options.credentials === void 0 ? {} : { credentials: options.credentials }
+    });
+    const shared = {
+      client: this.client,
+      bucket: options.bucket,
+      ...options.prefix === void 0 ? {} : { prefix: options.prefix }
+    };
+    this.storage = new S3StorageDriver(shared);
+    this.registry = new S3RegistryDriver({
+      ...shared,
+      ...options.now === void 0 ? {} : { now: options.now }
+    });
+    brandAsBackend(this);
+  }
+};
+export {
+  S3RegistryDriver,
+  S3Storage,
+  S3StorageDriver
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/storage.ts", "../src/keys.ts", "../src/s3-errors.ts", "../src/registry.ts", "../src/backend.ts"],
+  "sourcesContent": ["/**\n * `S3StorageDriver` \u2014 an {@link IStorageDriver} over S3-compatible object storage.\n *\n * Works with AWS S3 and any compatible backend (MinIO, etc.) via the official `@aws-sdk/client-s3`, a real\n * dependency of this package \u2014 installing `@cloudbitmaps/s3` is what installs it. The client is\n * **injected** (dependency injection): the driver owns no credential/region/endpoint logic, so it's thin,\n * testable against MinIO (point a client at its endpoint), and reuses the caller's existing client.\n *\n * Generations are write-once immutable objects: a conditional `PutObject` with `If-None-Match: *` makes the\n * publish atomic \u2014 a second write to the same key fails with `WriteConflictError`, never a silent overwrite\n * (hard invariant 2: storage objects are immutable and never overwritten in place), the cloud analogue of\n * the LocalFs atomic `link`. **This requires a backend that honors\n * `If-None-Match: *`** (AWS S3 \u2014 GA Aug 2024; recent MinIO): a backend that silently ignored the\n * precondition would break write-once immutability. **Writes stream:** the object is uploaded in\n * constant memory \u2014 a small object is a single conditional `PutObject`; a large one is a **multipart upload**\n * (parts flushed as the codec writes, freed as they go) finished with a conditional `CompleteMultipartUpload`,\n * so a load's footprint stays ~one part regardless of segment size, up to the advertised `maxObjectBytes`\n * (default `partBytes \u00D7 10,000` \u2014 S3's per-upload part limit). Drivers may use `node:crypto`; only `core/`\n * is bound by the determinism lint.\n */\nimport {\n  NotFoundError,\n  TransientError,\n  ValidationError,\n  WriteConflictError,\n  isNotFoundError,\n  isValidationError,\n  isWriteConflictError,\n} from '@cloudbitmaps/core/driver-kit';\nimport type {\n  BlobSink,\n  GenKey,\n  IStorageDriver,\n  SegmentRef,\n  StorageCaps,\n} from '@cloudbitmaps/core/driver-kit';\nimport { createHash, type Hash } from 'node:crypto';\nimport {\n  AbortMultipartUploadCommand,\n  CompleteMultipartUploadCommand,\n  CreateMultipartUploadCommand,\n  DeleteObjectCommand,\n  GetObjectCommand,\n  HeadObjectCommand,\n  ListObjectsV2Command,\n  PutObjectCommand,\n  UploadPartCommand,\n  type S3Client,\n} from '@aws-sdk/client-s3';\nimport {\n  storageObjectKey,\n  normalizeS3Prefix,\n  parseGenerationFromKey,\n  segmentObjectPrefix,\n} from './keys';\nimport {\n  isConditionalConflict,\n  isInvalidRange,\n  isNotFound,\n  isTransient,\n  totalFromContentRange,\n} from './s3-errors';\n\n/** Part size for multipart uploads. \u2265 the S3 5 MiB minimum; an object that fits in one part uses a single\n * conditional PUT instead (no multipart overhead, strongest write-once). Peak write memory \u2248 one part. */\nconst S3_PART_BYTES = 8 * 1024 * 1024;\n/** S3 hard limit: a multipart upload has at most 10,000 parts. This \u00D7 the part size is the real object ceiling. */\nconst S3_MAX_PARTS = 10_000;\n\nexport interface S3StorageDriverOptions {\n  /** A constructed S3 client (point its `endpoint` at MinIO for local/integration use). */\n  readonly client: S3Client;\n  /** Target bucket (must already exist). */\n  readonly bucket: string;\n  /** Optional key prefix under which all objects live (e.g. `cloudroaring/`). */\n  readonly prefix?: string;\n  /**\n   * Largest object this driver will write/advertise. Default = `partBytes \u00D7 10,000` (\u2248 80 GiB at the default\n   * 8 MiB part) \u2014 the honest ceiling reachable within S3's 10,000-part limit. Set it higher and `partBytes`\n   * auto-grows so 10,000 parts still cover it (raising peak write memory to ~one part); up to the 5 TiB S3 max.\n   */\n  readonly maxObjectBytes?: number;\n  /** Multipart part size in bytes (default 8 MiB; clamped to the S3 5 MiB minimum). Tunes peak write memory. */\n  readonly partBytes?: number;\n}\n\nexport class S3StorageDriver implements IStorageDriver {\n  private readonly client: S3Client;\n  private readonly bucket: string;\n  private readonly prefix: string | undefined;\n  private readonly maxObjectBytes: number;\n  private readonly partBytes: number;\n\n  constructor(options: S3StorageDriverOptions) {\n    this.client = options.client;\n    this.bucket = options.bucket;\n    this.prefix = normalizeS3Prefix(options.prefix);\n    const requestedPart = Math.max(options.partBytes ?? S3_PART_BYTES, 5 * 1024 * 1024);\n    // Default the object cap to what the requested part size can actually cover within S3's 10,000-part limit;\n    // if a larger cap is requested, grow the part size to keep it reachable (so the advertised cap is honest).\n    this.maxObjectBytes = options.maxObjectBytes ?? requestedPart * S3_MAX_PARTS;\n    this.partBytes = Math.max(requestedPart, Math.ceil(this.maxObjectBytes / S3_MAX_PARTS));\n  }\n\n  capabilities(): StorageCaps {\n    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };\n  }\n\n  async putImmutable(\n    key: GenKey,\n    write: (sink: BlobSink) => Promise<void>,\n  ): Promise<{ size: number; sha256: string }> {\n    const objectKey = storageObjectKey(this.prefix, key); // validates ref + generation\n    const sink = new S3MultipartSink(\n      this.client,\n      this.bucket,\n      objectKey,\n      this.partBytes,\n      this.maxObjectBytes,\n    );\n    try {\n      await write(sink);\n      return await sink.finish();\n    } catch (err) {\n      await sink.abort(); // best-effort cleanup of any in-flight multipart upload\n      // A lost conditional-write race \u2014 the precondition failed (412) or S3 rejected concurrent conditional\n      // writes to the key (409) \u2014 is the write-once conflict, never a silent overwrite.\n      if (isConditionalConflict(err)) {\n        throw new WriteConflictError(\n          `generation already exists (write-once): ${key.segment}.${key.generation}`,\n        );\n      }\n      if (isValidationError(err) || isWriteConflictError(err) || isNotFoundError(err)) {\n        throw err;\n      }\n      throw this.mapError(err);\n    }\n  }\n\n  async getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array> {\n    if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {\n      throw new ValidationError(`invalid range offset=${offset} length=${length}`);\n    }\n    const objectKey = storageObjectKey(this.prefix, key);\n    if (length === 0) return new Uint8Array(0);\n    try {\n      const res = await this.client.send(\n        new GetObjectCommand({\n          Bucket: this.bucket,\n          Key: objectKey,\n          Range: `bytes=${offset}-${offset + length - 1}`,\n        }),\n      );\n      const bytes = await collect(res.Body);\n      // A short read means the range ran past EOF \u2014 treat as out-of-bounds, never a partial result.\n      if (bytes.length !== length) {\n        throw new ValidationError(\n          `range [${offset}, ${offset + length}) out of bounds (got ${bytes.length}B)`,\n        );\n      }\n      return bytes;\n    } catch (err) {\n      throw this.mapReadError(err, key);\n    }\n  }\n\n  async getTail(key: GenKey, maxBytes: number): Promise<{ bytes: Uint8Array; size: number }> {\n    const objectKey = storageObjectKey(this.prefix, key);\n    if (maxBytes <= 0) {\n      // No tail bytes wanted \u2014 just resolve the size via a HEAD.\n      try {\n        const head = await this.client.send(\n          new HeadObjectCommand({ Bucket: this.bucket, Key: objectKey }),\n        );\n        return { bytes: new Uint8Array(0), size: head.ContentLength ?? 0 };\n      } catch (err) {\n        throw this.mapReadError(err, key);\n      }\n    }\n    try {\n      const res = await this.client.send(\n        new GetObjectCommand({ Bucket: this.bucket, Key: objectKey, Range: `bytes=-${maxBytes}` }),\n      );\n      const bytes = await collect(res.Body);\n      let size = totalFromContentRange(res.ContentRange);\n      if (size === undefined) {\n        // A spec-compliant backend omits Content-Range only on a 200 (whole object), where bytes.length\n        // IS the size. If the body is exactly maxBytes we can't rule out a clamped partial from a\n        // non-compliant backend \u2014 confirm the true size with a HEAD rather than trust a possibly-short read.\n        if (bytes.length === maxBytes) {\n          const head = await this.client.send(\n            new HeadObjectCommand({ Bucket: this.bucket, Key: objectKey }),\n          );\n          size = head.ContentLength ?? bytes.length;\n        } else {\n          size = bytes.length;\n        }\n      }\n      return { bytes, size };\n    } catch (err) {\n      throw this.mapReadError(err, key);\n    }\n  }\n\n  async delete(key: GenKey): Promise<void> {\n    // Idempotent: S3 DeleteObject succeeds even if the key is absent (GC may race / retry).\n    try {\n      await this.client.send(\n        new DeleteObjectCommand({ Bucket: this.bucket, Key: storageObjectKey(this.prefix, key) }),\n      );\n    } catch (err) {\n      throw this.mapError(err);\n    }\n  }\n\n  async *list(ref: SegmentRef): AsyncIterable<GenKey> {\n    const prefix = segmentObjectPrefix(this.prefix, ref); // validates ref\n    let token: string | undefined;\n    do {\n      let res;\n      try {\n        res = await this.client.send(\n          new ListObjectsV2Command({\n            Bucket: this.bucket,\n            Prefix: prefix,\n            ContinuationToken: token,\n          }),\n        );\n      } catch (err) {\n        throw this.mapError(err);\n      }\n      for (const obj of res.Contents ?? []) {\n        if (obj.Key === undefined) continue;\n        const generation = parseGenerationFromKey(prefix, obj.Key);\n        if (generation !== null) {\n          yield { namespace: ref.namespace, segment: ref.segment, generation };\n        }\n      }\n      token = res.IsTruncated === true ? res.NextContinuationToken : undefined;\n    } while (token !== undefined);\n  }\n\n  /** Map S3 read errors to the driver vocabulary; pass everything else through {@link mapError}. */\n  private mapReadError(err: unknown, key: GenKey): unknown {\n    if (isValidationError(err)) return err;\n    if (isNotFound(err)) {\n      return new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);\n    }\n    // A fully out-of-range request (start past EOF) \u2014 the BlobReader contract treats range errors as\n    // ValidationError, never a short/empty read.\n    if (isInvalidRange(err)) {\n      return new ValidationError(`range out of bounds for ${key.segment}.${key.generation}`);\n    }\n    return this.mapError(err);\n  }\n\n  /**\n   * Reclassify a transient S3 fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}\n   * so the retry decorator can ride it out; everything else propagates unchanged. The final fallback at every\n   * `client.send` site, so callers and the decorator only ever see typed errors.\n   */\n  private mapError(err: unknown): unknown {\n    if (isTransient(err)) {\n      return new TransientError(\n        `transient S3 fault: ${(err as { name?: string } | null)?.name ?? 'unknown'}`,\n        { cause: err },\n      );\n    }\n    return err;\n  }\n}\n\n/** Concatenate a list of byte chunks of known total length into one buffer. */\nfunction concatBytes(parts: readonly Uint8Array[], total: number): Uint8Array {\n  const out = new Uint8Array(total);\n  let offset = 0;\n  for (const p of parts) {\n    out.set(p, offset);\n    offset += p.length;\n  }\n  return out;\n}\n\n/**\n * Streaming {@link BlobSink} that uploads one S3 object in **constant memory**. It buffers at most\n * one part: as the codec writes, full parts are flushed via `UploadPart` and freed. A small object that never\n * reaches one part is committed as a single conditional `PutObject`; a larger one is finished with a\n * conditional `CompleteMultipartUpload` \u2014 **both enforce write-once** via `If-None-Match: *`. SHA-256 is hashed\n * incrementally. On any error the caller invokes {@link abort} to clean up the in-flight multipart upload.\n */\nclass S3MultipartSink implements BlobSink {\n  private readonly hash: Hash = createHash('sha256');\n  private readonly pending: Uint8Array[] = [];\n  private pendingLen = 0;\n  private total = 0;\n  private uploadId: string | undefined;\n  private partNumber = 0;\n  private readonly parts: { ETag: string | undefined; PartNumber: number }[] = [];\n\n  constructor(\n    private readonly client: S3Client,\n    private readonly bucket: string,\n    private readonly objectKey: string,\n    private readonly partBytes: number,\n    private readonly maxObjectBytes: number,\n  ) {}\n\n  async write(bytes: Uint8Array): Promise<void> {\n    if (bytes.length === 0) return;\n    this.total += bytes.length;\n    if (this.total > this.maxObjectBytes) {\n      // Fail fast + typed, rather than a late opaque S3 error (and abort the in-flight upload via the caller).\n      throw new ValidationError(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);\n    }\n    this.hash.update(bytes);\n    this.pending.push(bytes);\n    this.pendingLen += bytes.length;\n    if (this.pendingLen >= this.partBytes) await this.flushPart();\n  }\n\n  /** Upload the buffered bytes (\u2265 one part) as a single part, freeing them. Starts the upload on first call. */\n  private async flushPart(): Promise<void> {\n    if (this.uploadId === undefined) {\n      const res = await this.client.send(\n        new CreateMultipartUploadCommand({ Bucket: this.bucket, Key: this.objectKey }),\n      );\n      if (res.UploadId === undefined) {\n        throw new TransientError('S3 CreateMultipartUpload returned no UploadId');\n      }\n      this.uploadId = res.UploadId;\n    }\n    const body = concatBytes(this.pending, this.pendingLen);\n    this.pending.length = 0;\n    this.pendingLen = 0;\n    this.partNumber += 1;\n    if (this.partNumber > S3_MAX_PARTS) {\n      // Unreachable for valid input (the maxObjectBytes byte-cap, sized to \u2264 S3_MAX_PARTS parts, fires first) \u2014\n      // a typed guard so the S3 hard limit is never a raw 400.\n      throw new ValidationError(`multipart upload exceeded the S3 ${S3_MAX_PARTS}-part limit`);\n    }\n    const res = await this.client.send(\n      new UploadPartCommand({\n        Bucket: this.bucket,\n        Key: this.objectKey,\n        UploadId: this.uploadId,\n        PartNumber: this.partNumber,\n        Body: body,\n      }),\n    );\n    this.parts.push({ ETag: res.ETag, PartNumber: this.partNumber });\n  }\n\n  /** Commit the object: a single conditional PUT if it fit in one part, else complete the multipart upload. */\n  async finish(): Promise<{ size: number; sha256: string }> {\n    const sha256 = this.hash.digest('hex');\n    if (this.uploadId === undefined) {\n      await this.client.send(\n        new PutObjectCommand({\n          Bucket: this.bucket,\n          Key: this.objectKey,\n          Body: concatBytes(this.pending, this.pendingLen),\n          IfNoneMatch: '*', // write-once\n        }),\n      );\n      return { size: this.total, sha256 };\n    }\n    if (this.pendingLen > 0) await this.flushPart(); // the final part may be < partBytes (allowed)\n    await this.client.send(\n      new CompleteMultipartUploadCommand({\n        Bucket: this.bucket,\n        Key: this.objectKey,\n        UploadId: this.uploadId,\n        MultipartUpload: { Parts: this.parts },\n        IfNoneMatch: '*', // write-once: fail if the object already exists\n      }),\n    );\n    this.uploadId = undefined; // completed \u2014 nothing left to abort\n    return { size: this.total, sha256 };\n  }\n\n  /** Best-effort cleanup of an in-flight multipart upload after an error (a leaked MPU is reaped by a bucket\n   * lifecycle rule; never a correctness issue). No-op if nothing was started or it already completed. */\n  async abort(): Promise<void> {\n    if (this.uploadId === undefined) return;\n    const id = this.uploadId;\n    this.uploadId = undefined;\n    try {\n      await this.client.send(\n        new AbortMultipartUploadCommand({ Bucket: this.bucket, Key: this.objectKey, UploadId: id }),\n      );\n    } catch {\n      // swallow \u2014 best-effort\n    }\n  }\n}\n\n/**\n * Collect an S3 response body into a `Uint8Array`. `transformToByteArray` is added at runtime to the SDK's\n * Node stream by `@aws-sdk`'s sdk-stream-mixin, so the structural cast is sound on Node.\n */\nasync function collect(body: GetObjectCommandBody): Promise<Uint8Array> {\n  if (body === undefined) {\n    throw new NotFoundError('S3 GetObject returned an empty body');\n  }\n  return body.transformToByteArray();\n}\n\n/** The S3 `GetObject` Body type, narrowed to the part we use (`transformToByteArray`). */\ntype GetObjectCommandBody = { transformToByteArray(): Promise<Uint8Array> } | undefined;\n", "/**\n * Logical-ref \u2192 S3 object-key mapping for {@link S3StorageDriver}.\n *\n * Pure string logic with no SDK dependency, so it's unit-testable without S3/MinIO. Mirrors the LocalFs\n * layout (`<namespace>/segments/<segment>.<gen>.crbm`) under an optional caller prefix, and re-validates\n * names at the boundary \u2014 defense in depth, because a driver can be constructed and driven directly rather\n * than through the engine that would otherwise have validated for it. The default\n * (absent) namespace maps to `_default`, which cannot collide with a real namespace because a caller's\n * `_default` encodes to `%5Fdefault` while the sentinel is emitted literally.\n */\n// `prefixPart` is imported, never redefined: the storage and registry layouts sit under the SAME caller\n// prefix, so they must normalize it identically \u2014 a second copy of that three-line function is how the two\n// halves of one bucket drift apart.\nimport {\n  ValidationError,\n  encodeNameForKey,\n  namespaceKeyPart,\n  prefixPart,\n  validateSegmentRef,\n} from '@cloudbitmaps/core/driver-kit';\nimport type { GenKey, SegmentRef } from '@cloudbitmaps/core/driver-kit';\n\nconst SUFFIX = '.crbm';\n\n/** Validate a caller-supplied key prefix. The rule is shared with every other object store. */\nexport { normalizeObjectPrefix as normalizeS3Prefix } from '@cloudbitmaps/core/driver-kit';\n\n/**\n * The S3 key prefix shared by all of a segment's generations: `<prefix><ns>/segments/<segment>.`. Used\n * both as the `ListObjectsV2` prefix and as the string stripped by {@link parseGenerationFromKey}.\n */\nexport function segmentObjectPrefix(prefix: string | undefined, ref: SegmentRef): string {\n  validateSegmentRef(ref);\n  return `${prefixPart(prefix)}${namespaceKeyPart(ref.namespace)}/segments/${encodeNameForKey(ref.segment)}.`;\n}\n\n/** The full S3 key of one `.crbm` generation: `<segmentPrefix><gen>.crbm`. */\nexport function storageObjectKey(prefix: string | undefined, key: GenKey): string {\n  if (!Number.isInteger(key.generation) || key.generation < 0) {\n    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);\n  }\n  return `${segmentObjectPrefix(prefix, key)}${key.generation}${SUFFIX}`;\n}\n\n// \u2500\u2500\u2500 Registry keys \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// The registry layout is identical across S3, GCS and Azure Blob \u2014 all three encode names the same way and\n// build byte-identical keys \u2014 so it lives in `_shared/object-registry-keys` and is re-exported here for the\n// callers (and tests) that already name it through this module.\nexport {\n  registryPrefix,\n  registryObjectKey,\n  registryListPrefix,\n  parseRegistryKey,\n} from '@cloudbitmaps/core/driver-kit';\n\n/**\n * Parse a generation number out of a full object key, given its segment prefix, or `null` if it doesn't\n * match. Canonical decimal only \u2014 no leading zeros (so `\u2026s.07.crbm` can't alias `\u2026s.7.crbm`) and within\n * safe-integer range. This also rejects a *different* segment whose name merely shares the prefix (e.g. a\n * key for segment `s.x` won't parse under segment `s`'s prefix, since its middle isn't all digits).\n */\nexport function parseGenerationFromKey(segmentPrefix: string, objectKey: string): number | null {\n  if (!objectKey.startsWith(segmentPrefix) || !objectKey.endsWith(SUFFIX)) return null;\n  const middle = objectKey.slice(segmentPrefix.length, objectKey.length - SUFFIX.length);\n  if (!/^(0|[1-9]\\d*)$/.test(middle)) return null;\n  const generation = Number(middle);\n  return Number.isSafeInteger(generation) ? generation : null;\n}\n", "/**\n * Pure helpers for classifying S3 SDK errors + parsing response headers (conflict and transient classification).\n *\n * Kept SDK-free and side-effect-free (they only read structural shapes \u2014 `err.name`,\n * `$metadata.httpStatusCode`, a `Content-Range` string) so the subtle S3-specific translation logic is\n * unit-testable without a live MinIO/S3 or even the AWS SDK. Shared AWS shapes come from `_shared/aws-errors`.\n */\n\nimport {\n  errorName,\n  httpStatus,\n  isNetworkOrTimeout,\n  isSdkRetryable,\n  isServerSide,\n} from '@cloudbitmaps/core/driver-kit';\n\n/** A conditional `If-None-Match: *` PUT lost the write-once race (the object already existed). */\nexport function isPreconditionFailed(err: unknown): boolean {\n  return errorName(err) === 'PreconditionFailed' || httpStatus(err) === 412;\n}\n\n/**\n * A conditional write (`If-None-Match: *` / `If-Match: <etag>`) lost the race \u2014 **either** outcome S3 uses:\n * the precondition evaluated false (`412 PreconditionFailed`), **or** S3 rejected concurrent conditional\n * writes to the same key to prevent a lost update (`409 ConditionalRequestConflict`, which AWS documents and\n * asks you to retry). Both mean \"you lost; re-read and retry\" \u2014 so both must map to `WriteConflictError` and\n * route through the caller's OCC path, never a blind transient retry (which would just replay a doomed PUT).\n */\nexport function isConditionalConflict(err: unknown): boolean {\n  return (\n    isPreconditionFailed(err) ||\n    errorName(err) === 'ConditionalRequestConflict' ||\n    httpStatus(err) === 409\n  );\n}\n\n/** The object / generation does not exist (GetObject \u2192 `NoSuchKey`, HeadObject \u2192 `NotFound`; both 404). */\nexport function isNotFound(err: unknown): boolean {\n  const name = errorName(err);\n  return name === 'NoSuchKey' || name === 'NotFound' || httpStatus(err) === 404;\n}\n\n/** A range request started past EOF (HTTP 416). */\nexport function isInvalidRange(err: unknown): boolean {\n  return errorName(err) === 'InvalidRange' || httpStatus(err) === 416;\n}\n\n/**\n * A transient S3 fault that is safe to retry: throttling (`SlowDown` / 503), any 5xx, a dropped/timed-out\n * connection, or anything the SDK itself marks retryable. Excludes the deterministic outcomes above\n * (412/404/416) \u2014 those are caller-meaningful and must never be retried/reclassified.\n */\nexport function isTransient(err: unknown): boolean {\n  // A conditional-write conflict (412/409) is caller-meaningful OCC, not a blind-retryable transient.\n  if (isConditionalConflict(err) || isNotFound(err) || isInvalidRange(err)) return false;\n  return (\n    errorName(err) === 'SlowDown' ||\n    isServerSide(err) ||\n    isNetworkOrTimeout(err) ||\n    isSdkRetryable(err)\n  );\n}\n\n/**\n * Parse the total object size out of a `Content-Range: bytes <start>-<end>/<total>` header, or `undefined`\n * if absent/unparseable/unsafe. The total is the part after the final `/`.\n */\nexport function totalFromContentRange(contentRange: string | undefined): number | undefined {\n  if (contentRange === undefined) return undefined;\n  const match = /\\/(\\d+)\\s*$/.exec(contentRange);\n  if (match === null) return undefined;\n  const total = Number(match[1]);\n  return Number.isSafeInteger(total) ? total : undefined;\n}\n", "/**\n * `S3RegistryDriver` \u2014 an {@link IRegistryDriver} over S3-compatible object storage.\n *\n * Lets a **read-mostly deployment run on S3 alone** \u2014 storage `.crbm` generations + the registry in one bucket,\n * no separate database. The protocol (an ABA-safe OCC counter, tombstoning delete, the bounded retry, the key layout)\n * lives once in {@link ObjectStoreRegistry}; this file is only the three I/O calls S3 makes, so the S3, GCS\n * and Azure registries cannot drift from one another.\n *\n * **The atomic swap is offloaded to S3's conditional writes** (GA Nov 2024): `If-None-Match: *` for\n * create-only and `If-Match: <etag>` for compare-and-swap, so a concurrent writer between our read and our\n * PUT loses with a `412` \u2192 {@link WriteConflictError}. Reads are strongly consistent (S3, since 2020),\n * satisfying the registry's `strongRead` contract. The client is **injected**, exactly like\n * {@link S3StorageDriver}.\n *\n * **Deployment requirements** (a backend/policy that violates these silently corrupts the registry):\n * - The backend **must honor `If-Match`** (AWS S3; recent MinIO). One that returns ETags but ignores the\n *   precondition degrades compare-and-swap to last-write-wins \u2192 lost `currentGen` swaps. Verified against\n *   real S3 semantics by the MinIO integration lane.\n * - The IAM principal needs **`s3:ListBucket`** on the bucket. Without it, `GetObject` on a missing key\n *   returns `403` (not `404`), so the \"absent segment \u2192 `null`\" contract (and `create`'s bootstrap read)\n *   breaks \u2014 and `list()` needs it regardless.\n * - **Do not apply an S3 lifecycle-expiration rule to the `registry/` prefix.** See {@link ObjectStoreRegistry}.\n */\nimport {\n  IntegrityError,\n  MAX_ROW_BYTES,\n  ObjectStoreRegistry,\n  TransientError,\n  WriteConflictError,\n  normalizeObjectPrefix,\n} from '@cloudbitmaps/core/driver-kit';\nimport type { ObjectRegistryStore, ObjectRow } from '@cloudbitmaps/core/driver-kit';\nimport {\n  GetObjectCommand,\n  ListObjectsV2Command,\n  PutObjectCommand,\n  type S3Client,\n} from '@aws-sdk/client-s3';\nimport { isConditionalConflict, isNotFound, isTransient } from './s3-errors';\n\nexport interface S3RegistryDriverOptions {\n  /** A constructed S3 client (point its `endpoint` at MinIO for local/integration use). */\n  readonly client: S3Client;\n  /** Target bucket (must already exist). */\n  readonly bucket: string;\n  /** Optional key prefix under which all registry objects live (e.g. `cloudroaring/`). */\n  readonly prefix?: string;\n  /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now`. */\n  readonly now?: () => number;\n}\n\n/** The three calls {@link ObjectStoreRegistry} needs, in S3's dialect. */\nclass S3Store implements ObjectRegistryStore {\n  readonly label = 'S3';\n\n  constructor(\n    private readonly client: S3Client,\n    private readonly bucket: string,\n  ) {}\n\n  async read(key: string): Promise<ObjectRow | null> {\n    let res;\n    try {\n      res = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: key }));\n    } catch (err) {\n      if (isNotFound(err)) return null;\n      throw mapError(err);\n    }\n    // Check the advertised length BEFORE allocating, so a hostile object cannot make us buffer it first.\n    if ((res.ContentLength ?? 0) > MAX_ROW_BYTES) {\n      throw new IntegrityError(\n        `registry object ${res.ContentLength}B exceeds cap ${MAX_ROW_BYTES}B`,\n      );\n    }\n    if (res.Body === undefined) {\n      throw new IntegrityError(`registry object has an empty body: ${key}`);\n    }\n    const bytes = await (\n      res.Body as { transformToByteArray(): Promise<Uint8Array> }\n    ).transformToByteArray();\n    return { bytes, version: res.ETag ?? '' };\n  }\n\n  async write(\n    key: string,\n    body: Uint8Array,\n    expect: 'absent' | { version: string },\n  ): Promise<void> {\n    try {\n      await this.client.send(\n        new PutObjectCommand({\n          Bucket: this.bucket,\n          Key: key,\n          Body: body,\n          ContentType: 'application/json',\n          IfNoneMatch: expect === 'absent' ? '*' : undefined,\n          IfMatch: expect === 'absent' ? undefined : expect.version,\n        }),\n      );\n    } catch (err) {\n      // A lost conditional-write race (412 precondition, or 409 concurrent-conflict) is an OCC conflict.\n      if (isConditionalConflict(err)) {\n        throw new WriteConflictError(`registry OCC conflict for ${key}`);\n      }\n      throw mapError(err);\n    }\n  }\n\n  async *listKeys(prefix: string): AsyncIterable<string> {\n    let token: string | undefined;\n    do {\n      let res;\n      try {\n        res = await this.client.send(\n          new ListObjectsV2Command({\n            Bucket: this.bucket,\n            Prefix: prefix,\n            ContinuationToken: token,\n          }),\n        );\n      } catch (err) {\n        throw mapError(err);\n      }\n      for (const obj of res.Contents ?? []) {\n        if (obj.Key !== undefined) yield obj.Key;\n      }\n      token = res.IsTruncated === true ? res.NextContinuationToken : undefined;\n    } while (token !== undefined);\n  }\n}\n\n/** Reclassify a transient S3 fault as a retryable {@link TransientError}; pass everything else through. */\nfunction mapError(err: unknown): unknown {\n  if (isTransient(err)) {\n    return new TransientError(\n      `transient S3 fault: ${(err as { name?: string } | null)?.name ?? 'unknown'}`,\n      { cause: err },\n    );\n  }\n  return err;\n}\n\nexport class S3RegistryDriver extends ObjectStoreRegistry {\n  constructor(options: S3RegistryDriverOptions) {\n    super(\n      new S3Store(options.client, options.bucket),\n      normalizeObjectPrefix(options.prefix),\n      options.now ?? ((): number => Date.now()),\n    );\n  }\n}\n", "/**\n * `S3Storage` \u2014 the S3 backend as one object: the generations and the pointer, in one bucket, stated once.\n *\n * Replaces two constructor calls that each repeated `client`, `bucket` and `prefix`. Repeating them is how\n * they come apart: point the registry at one prefix and the objects at another and the store answers *empty*\n * rather than *misconfigured*, which is the hardest kind of wrong answer to debug. Here the location is written\n * once and shared, so the mismatch cannot be expressed.\n *\n * **It will build a client for you**, which is the common case \u2014 `new S3Storage({ bucket })` picks up the\n * ambient credential chain and region exactly as the SDK would. Pass `client` instead when you need a\n * credential chain the SDK cannot infer (SSO, an assumed role, a custom retry strategy); pass `endpoint` +\n * `pathStyle` + `credentials` for an S3-compatible store (MinIO, Ceph, R2). Both halves stay reachable as `.storage` and\n * `.registry` for anyone wiring something the facade does not cover.\n */\nimport { STORAGE_BACKEND, brandAsBackend } from '@cloudbitmaps/core/driver-kit';\nimport type {\n  IRegistryDriver,\n  IStorageDriver,\n  StorageBackend,\n} from '@cloudbitmaps/core/driver-kit';\nimport { S3Client } from '@aws-sdk/client-s3';\nimport { S3StorageDriver } from './storage';\nimport { S3RegistryDriver } from './registry';\n\nexport interface S3StorageOptions {\n  /** Target bucket (must already exist). */\n  readonly bucket: string;\n  /** Optional key prefix under which everything lives \u2014 generations and the registry alike. */\n  readonly prefix?: string;\n  /** A constructed client. Supply one for a credential chain the SDK cannot infer; otherwise one is built. */\n  readonly client?: S3Client;\n  /** Region for the client built when `client` is absent. Falls back to the SDK's own resolution. */\n  readonly region?: string;\n  /** Endpoint for an S3-compatible store (MinIO, Ceph, R2). Ignored when `client` is supplied. */\n  readonly endpoint?: string;\n  /** Path-style addressing, which most S3-compatible stores require. Ignored when `client` is supplied. */\n  readonly pathStyle?: boolean;\n  /**\n   * Static credentials, for the S3-compatible stores that issue them (MinIO, Ceph, R2).\n   *\n   * On AWS itself, leave this unset \u2014 the SDK's own chain (instance role, SSO, environment, profile) is what\n   * you want, and hard-coding keys to reach it would be a downgrade. It exists because the alternative for a\n   * MinIO user was to construct an `S3Client` purely to carry two strings, which is the ergonomics this class\n   * is here to remove. Ignored when `client` is supplied.\n   */\n  readonly credentials?: {\n    readonly accessKeyId: string;\n    readonly secretAccessKey: string;\n    readonly sessionToken?: string;\n  };\n  /** Injected clock for the registry's `createdAt`/`updatedAt`; defaults to `Date.now`. */\n  readonly now?: () => number;\n}\n\nexport class S3Storage implements StorageBackend {\n  /** Cross-bundle brand, stamped non-enumerably in the constructor so a spread cannot carry it. */\n  declare readonly [STORAGE_BACKEND]: true;\n  readonly storage: IStorageDriver;\n  readonly registry: IRegistryDriver;\n  /** The client both halves share \u2014 built here unless one was supplied. */\n  readonly client: S3Client;\n\n  constructor(options: S3StorageOptions) {\n    this.client =\n      options.client ??\n      new S3Client({\n        ...(options.region === undefined ? {} : { region: options.region }),\n        ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),\n        ...(options.pathStyle === undefined ? {} : { forcePathStyle: options.pathStyle }),\n        ...(options.credentials === undefined ? {} : { credentials: options.credentials }),\n      });\n    const shared = {\n      client: this.client,\n      bucket: options.bucket,\n      ...(options.prefix === undefined ? {} : { prefix: options.prefix }),\n    };\n    this.storage = new S3StorageDriver(shared);\n    this.registry = new S3RegistryDriver({\n      ...shared,\n      ...(options.now === undefined ? {} : { now: options.now }),\n    });\n    brandAsBackend(this);\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["ValidationError", "ValidationError", "res", "TransientError", "WriteConflictError", "normalizeObjectPrefix", "GetObjectCommand", "ListObjectsV2Command", "PutObjectCommand", "GetObjectCommand", "PutObjectCommand", "WriteConflictError", "ListObjectsV2Command", "TransientError", "normalizeObjectPrefix"]
+}

package/dist/keys.d.ts

@@ -0,0 +1,18 @@
+import type { GenKey, SegmentRef } from '@cloudbitmaps/core/driver-kit';
+/** Validate a caller-supplied key prefix. The rule is shared with every other object store. */
+export { normalizeObjectPrefix as normalizeS3Prefix } from '@cloudbitmaps/core/driver-kit';
+/**
+ * The S3 key prefix shared by all of a segment's generations: `<prefix><ns>/segments/<segment>.`. Used
+ * both as the `ListObjectsV2` prefix and as the string stripped by {@link parseGenerationFromKey}.
+ */
+export declare function segmentObjectPrefix(prefix: string | undefined, ref: SegmentRef): string;
+/** The full S3 key of one `.crbm` generation: `<segmentPrefix><gen>.crbm`. */
+export declare function storageObjectKey(prefix: string | undefined, key: GenKey): string;
+export { registryPrefix, registryObjectKey, registryListPrefix, parseRegistryKey, } from '@cloudbitmaps/core/driver-kit';
+/**
+ * Parse a generation number out of a full object key, given its segment prefix, or `null` if it doesn't
+ * match. Canonical decimal only — no leading zeros (so `…s.07.crbm` can't alias `…s.7.crbm`) and within
+ * safe-integer range. This also rejects a *different* segment whose name merely shares the prefix (e.g. a
+ * key for segment `s.x` won't parse under segment `s`'s prefix, since its middle isn't all digits).
+ */
+export declare function parseGenerationFromKey(segmentPrefix: string, objectKey: string): number | null;

package/dist/registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `S3RegistryDriver` — an {@link IRegistryDriver} over S3-compatible object storage.
+ *
+ * Lets a **read-mostly deployment run on S3 alone** — storage `.crbm` generations + the registry in one bucket,
+ * no separate database. The protocol (an ABA-safe OCC counter, tombstoning delete, the bounded retry, the key layout)
+ * lives once in {@link ObjectStoreRegistry}; this file is only the three I/O calls S3 makes, so the S3, GCS
+ * and Azure registries cannot drift from one another.
+ *
+ * **The atomic swap is offloaded to S3's conditional writes** (GA Nov 2024): `If-None-Match: *` for
+ * create-only and `If-Match: <etag>` for compare-and-swap, so a concurrent writer between our read and our
+ * PUT loses with a `412` → {@link WriteConflictError}. Reads are strongly consistent (S3, since 2020),
+ * satisfying the registry's `strongRead` contract. The client is **injected**, exactly like
+ * {@link S3StorageDriver}.
+ *
+ * **Deployment requirements** (a backend/policy that violates these silently corrupts the registry):
+ * - The backend **must honor `If-Match`** (AWS S3; recent MinIO). One that returns ETags but ignores the
+ *   precondition degrades compare-and-swap to last-write-wins → lost `currentGen` swaps. Verified against
+ *   real S3 semantics by the MinIO integration lane.
+ * - The IAM principal needs **`s3:ListBucket`** on the bucket. Without it, `GetObject` on a missing key
+ *   returns `403` (not `404`), so the "absent segment → `null`" contract (and `create`'s bootstrap read)
+ *   breaks — and `list()` needs it regardless.
+ * - **Do not apply an S3 lifecycle-expiration rule to the `registry/` prefix.** See {@link ObjectStoreRegistry}.
+ */
+import { ObjectStoreRegistry } from '@cloudbitmaps/core/driver-kit';
+import { type S3Client } from '@aws-sdk/client-s3';
+export interface S3RegistryDriverOptions {
+    /** A constructed S3 client (point its `endpoint` at MinIO for local/integration use). */
+    readonly client: S3Client;
+    /** Target bucket (must already exist). */
+    readonly bucket: string;
+    /** Optional key prefix under which all registry objects live (e.g. `cloudroaring/`). */
+    readonly prefix?: string;
+    /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+export declare class S3RegistryDriver extends ObjectStoreRegistry {
+    constructor(options: S3RegistryDriverOptions);
+}

package/dist/s3-errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure helpers for classifying S3 SDK errors + parsing response headers (conflict and transient classification).
+ *
+ * Kept SDK-free and side-effect-free (they only read structural shapes — `err.name`,
+ * `$metadata.httpStatusCode`, a `Content-Range` string) so the subtle S3-specific translation logic is
+ * unit-testable without a live MinIO/S3 or even the AWS SDK. Shared AWS shapes come from `_shared/aws-errors`.
+ */
+/** A conditional `If-None-Match: *` PUT lost the write-once race (the object already existed). */
+export declare function isPreconditionFailed(err: unknown): boolean;
+/**
+ * A conditional write (`If-None-Match: *` / `If-Match: <etag>`) lost the race — **either** outcome S3 uses:
+ * the precondition evaluated false (`412 PreconditionFailed`), **or** S3 rejected concurrent conditional
+ * writes to the same key to prevent a lost update (`409 ConditionalRequestConflict`, which AWS documents and
+ * asks you to retry). Both mean "you lost; re-read and retry" — so both must map to `WriteConflictError` and
+ * route through the caller's OCC path, never a blind transient retry (which would just replay a doomed PUT).
+ */
+export declare function isConditionalConflict(err: unknown): boolean;
+/** The object / generation does not exist (GetObject → `NoSuchKey`, HeadObject → `NotFound`; both 404). */
+export declare function isNotFound(err: unknown): boolean;
+/** A range request started past EOF (HTTP 416). */
+export declare function isInvalidRange(err: unknown): boolean;
+/**
+ * A transient S3 fault that is safe to retry: throttling (`SlowDown` / 503), any 5xx, a dropped/timed-out
+ * connection, or anything the SDK itself marks retryable. Excludes the deterministic outcomes above
+ * (412/404/416) — those are caller-meaningful and must never be retried/reclassified.
+ */
+export declare function isTransient(err: unknown): boolean;
+/**
+ * Parse the total object size out of a `Content-Range: bytes <start>-<end>/<total>` header, or `undefined`
+ * if absent/unparseable/unsafe. The total is the part after the final `/`.
+ */
+export declare function totalFromContentRange(contentRange: string | undefined): number | undefined;

package/dist/storage.d.ts

@@ -0,0 +1,46 @@
+import type { BlobSink, GenKey, IStorageDriver, SegmentRef, StorageCaps } from '@cloudbitmaps/core/driver-kit';
+import { type S3Client } from '@aws-sdk/client-s3';
+export interface S3StorageDriverOptions {
+    /** A constructed S3 client (point its `endpoint` at MinIO for local/integration use). */
+    readonly client: S3Client;
+    /** Target bucket (must already exist). */
+    readonly bucket: string;
+    /** Optional key prefix under which all objects live (e.g. `cloudroaring/`). */
+    readonly prefix?: string;
+    /**
+     * Largest object this driver will write/advertise. Default = `partBytes × 10,000` (≈ 80 GiB at the default
+     * 8 MiB part) — the honest ceiling reachable within S3's 10,000-part limit. Set it higher and `partBytes`
+     * auto-grows so 10,000 parts still cover it (raising peak write memory to ~one part); up to the 5 TiB S3 max.
+     */
+    readonly maxObjectBytes?: number;
+    /** Multipart part size in bytes (default 8 MiB; clamped to the S3 5 MiB minimum). Tunes peak write memory. */
+    readonly partBytes?: number;
+}
+export declare class S3StorageDriver implements IStorageDriver {
+    private readonly client;
+    private readonly bucket;
+    private readonly prefix;
+    private readonly maxObjectBytes;
+    private readonly partBytes;
+    constructor(options: S3StorageDriverOptions);
+    capabilities(): StorageCaps;
+    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
+        size: number;
+        sha256: string;
+    }>;
+    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
+    getTail(key: GenKey, maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+    delete(key: GenKey): Promise<void>;
+    list(ref: SegmentRef): AsyncIterable<GenKey>;
+    /** Map S3 read errors to the driver vocabulary; pass everything else through {@link mapError}. */
+    private mapReadError;
+    /**
+     * Reclassify a transient S3 fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}
+     * so the retry decorator can ride it out; everything else propagates unchanged. The final fallback at every
+     * `client.send` site, so callers and the decorator only ever see typed errors.
+     */
+    private mapError;
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@cloudbitmaps/s3",
+  "version": "0.10.0-rc.0",
+  "description": "S3 and S3-compatible storage (R2, MinIO, Ceph, Wasabi, B2) for CloudBitmaps",
+  "keywords": [
+    "cloudbitmaps",
+    "bitmap",
+    "roaring-bitmap",
+    "serverless",
+    "cloud",
+    "typescript",
+    "s3",
+    "aws",
+    "r2",
+    "minio",
+    "ceph",
+    "wasabi",
+    "backblaze",
+    "object-storage"
+  ],
+  "license": "Apache-2.0",
+  "author": "Sharvil Kadam",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudbitmaps/cloudbitmaps.git",
+    "directory": "packages/s3"
+  },
+  "homepage": "https://github.com/cloudbitmaps/cloudbitmaps#readme",
+  "bugs": {
+    "url": "https://github.com/cloudbitmaps/cloudbitmaps/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": ">=3.645.0 <4",
+    "@cloudbitmaps/core": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs"
+  }
+}