@cloudbitmaps/gcs 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/gcs
+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/gcs 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,70 @@
+# @cloudbitmaps/gcs
+
+**Google Cloud 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.
+
+Google Cloud Storage. Compare-and-swap rides GCS object preconditions, so a deployment runs on **one bucket alone** — no second service holds the pointer.
+
+## Install
+
+```bash
+pnpm add @cloudbitmaps/roaring @cloudbitmaps/gcs
+# npm i @cloudbitmaps/roaring @cloudbitmaps/gcs   # 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. `@google-cloud/storage` (`^7 || ^8`) 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.
+
+## Use
+
+```ts
+import { CloudRoaring } from '@cloudbitmaps/roaring';
+import { GcsStorage } from '@cloudbitmaps/gcs';
+
+const store = new CloudRoaring({
+  storage: new GcsStorage({ bucket: 'bitmaps', prefix: 'cr' }),
+});
+
+await store.load({ segment: 'active-users' }, [1, 2, 3]);
+const seg = store.segment('active-users');
+await seg.has(2); // true
+```
+
+`GcsStorage` 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,43 @@
+/**
+ * `GcsStorage` — the Google Cloud Storage backend as one object: generations and pointer, one bucket, stated once.
+ *
+ * See {@link StorageBackend} for why the two halves are configured together rather than separately.
+ *
+ * **A note on the word.** `@google-cloud/storage` names its own client class `Storage`, so the driver option
+ * that takes it is also called `storage` — which, since our durable tier is now called storage too, reads as
+ * the same word meaning two things. That is why this class builds the client itself: `new GcsStorage({ bucket })`
+ * never makes you write `{ storage: storage }`. Supply `client` when you need your own.
+ */
+import { STORAGE_BACKEND } from '@cloudbitmaps/core/driver-kit';
+import type { IRegistryDriver, IStorageDriver, StorageBackend } from '@cloudbitmaps/core/driver-kit';
+import { Storage as GcsClient } from '@google-cloud/storage';
+export interface GcsStorageOptions {
+    /** Target bucket (must already exist). */
+    readonly bucket: string;
+    /** Optional object-name prefix under which everything lives — generations and the registry alike. */
+    readonly prefix?: string;
+    /** A constructed `@google-cloud/storage` client. One is built from the ambient credentials when absent. */
+    readonly client?: GcsClient;
+    /**
+     * Not an option — the old `GcsStorageDriver` took the client as `storage`, and a migrating caller keeps the
+     * name. Typed `never` so the object literal is a compile error, and rejected at runtime for JavaScript
+     * callers, because silently ignoring it falls back to ambient credentials and the **public** endpoint: for
+     * anyone whose client pointed at an emulator, that is production traffic from a wiring typo.
+     */
+    readonly storage?: never;
+    /** Project id for the client built when `client` is absent. Falls back to the SDK's own resolution. */
+    readonly projectId?: string;
+    /** Endpoint override — point it at fake-gcs-server locally. Ignored when `client` is supplied. */
+    readonly apiEndpoint?: string;
+    /** Injected clock for the registry's `createdAt`/`updatedAt`; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+export declare class GcsStorage 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: GcsClient;
+    constructor(options: GcsStorageOptions);
+}

package/dist/gcs-errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure helpers for classifying Google Cloud Storage SDK errors (the transient class mirrors S3's).
+ *
+ * SDK-free + side-effect-free — they only read structural shapes off the thrown value (`err.code`,
+ * `err.response.status`, `err.name`), so the GCS-specific translation is unit-testable without a live GCS or
+ * an emulator, and without importing `@google-cloud/storage`. GCS's `ApiError` carries the HTTP status on
+ * `.code` (a number); dropped/timed-out sockets surface as a Node error with a string `.code` (`ECONNRESET`,
+ * `ETIMEDOUT`, …).
+ */
+/**
+ * A conditional `ifGenerationMatch: 0` write lost the write-once race — the object already existed, so GCS
+ * returns **412 Precondition Failed**. Maps to `WriteConflictError` (caller OCC), never a blind retry.
+ */
+export declare function isPreconditionFailed(err: unknown): boolean;
+/** The object / generation does not exist (GCS returns 404). */
+export declare function isNotFound(err: unknown): boolean;
+/** A range request started past EOF (HTTP 416 Requested Range Not Satisfiable). */
+export declare function isInvalidRange(err: unknown): boolean;
+/**
+ * A transient GCS fault that is safe to retry: throttling (429), any 5xx, or a dropped/timed-out socket.
+ * Excludes the deterministic, caller-meaningful outcomes (412/404/416) — those must never be reclassified as
+ * a blind transient (a retried doomed conditional write would just fail again, and mask an OCC conflict).
+ */
+export declare function isTransient(err: unknown): boolean;

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@cloudbitmaps/gcs` — Google Cloud Storage.
+ *
+ * One package per storage SERVICE, with `@google-cloud/storage` as a real dependency. Install it alongside a
+ * flavor package and wire the backend in one line:
+ *
+ * ```ts
+ * import { CloudRoaring } from '@cloudbitmaps/roaring';
+ * import { GcsStorage } from '@cloudbitmaps/gcs';
+ *
+ * const store = new CloudRoaring({ storage: new GcsStorage({ 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 { GcsStorageDriver } from './storage.js';
+export type { GcsStorageDriverOptions } from './storage.js';
+export { GcsRegistryDriver } from './registry.js';
+export type { GcsRegistryDriverOptions } from './registry.js';
+export { GcsStorage } from './backend.js';
+export type { GcsStorageOptions } from './backend.js';

package/dist/index.js

@@ -0,0 +1,430 @@
+// src/storage.ts
+import {
+  NotFoundError,
+  TransientError,
+  ValidationError as ValidationError2,
+  WriteConflictError,
+  isNotFoundError,
+  isValidationError,
+  isWriteConflictError
+} from "@cloudbitmaps/core/driver-kit";
+import { createHash } from "node:crypto";
+import { once } from "node:events";
+
+// src/keys.ts
+import {
+  ValidationError,
+  encodeNameForKey,
+  namespaceKeyPart,
+  prefixPart,
+  validateSegmentRef
+} from "@cloudbitmaps/core/driver-kit";
+var SUFFIX = ".crbm";
+function normalizeGcsPrefix(prefix) {
+  if (prefix === void 0) return void 0;
+  for (const ch of prefix) {
+    if (ch.charCodeAt(0) < 32) {
+      throw new ValidationError("prefix must not contain control characters");
+    }
+  }
+  for (const segment of prefix.split("/")) {
+    if (segment === "." || segment === "..") {
+      throw new ValidationError(
+        `prefix must not contain "." or ".." path segments: ${JSON.stringify(prefix)}`
+      );
+    }
+  }
+  return prefix;
+}
+function segmentObjectPrefix(prefix, ref) {
+  validateSegmentRef(ref);
+  return `${prefixPart(prefix)}${namespaceKeyPart(ref.namespace)}/segments/${encodeNameForKey(ref.segment)}.`;
+}
+function storageObjectName(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 parseGenerationFromName(segmentPrefix, objectName) {
+  if (!objectName.startsWith(segmentPrefix) || !objectName.endsWith(SUFFIX)) return null;
+  const middle = objectName.slice(segmentPrefix.length, objectName.length - SUFFIX.length);
+  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
+  const generation = Number(middle);
+  return Number.isSafeInteger(generation) ? generation : null;
+}
+
+// src/gcs-errors.ts
+function httpStatus(err) {
+  const e = err;
+  if (typeof e?.code === "number") return e.code;
+  if (typeof e?.response?.status === "number") return e.response.status;
+  return void 0;
+}
+function networkCode(err) {
+  const code = err?.code;
+  return typeof code === "string" ? code : void 0;
+}
+function isPreconditionFailed(err) {
+  return httpStatus(err) === 412;
+}
+function isNotFound(err) {
+  return httpStatus(err) === 404;
+}
+function isInvalidRange(err) {
+  return httpStatus(err) === 416;
+}
+function isTransient(err) {
+  if (isPreconditionFailed(err) || isNotFound(err) || isInvalidRange(err)) return false;
+  const status = httpStatus(err);
+  if (status === 429 || status !== void 0 && status >= 500 && status < 600) return true;
+  const net = networkCode(err);
+  return net === "ECONNRESET" || net === "ETIMEDOUT" || net === "ECONNREFUSED" || net === "EPIPE" || net === "EAI_AGAIN" || net === "ENOTFOUND";
+}
+
+// src/storage.ts
+var DEFAULT_MAX_OBJECT_BYTES = 5 * 1024 * 1024 * 1024 * 1024;
+var DEFAULT_UPLOAD_THRESHOLD_BYTES = 8 * 1024 * 1024;
+var GcsStorageDriver = class {
+  storage;
+  bucket;
+  prefix;
+  maxObjectBytes;
+  threshold;
+  constructor(options) {
+    this.storage = options.storage;
+    this.bucket = options.bucket;
+    this.prefix = normalizeGcsPrefix(options.prefix);
+    this.maxObjectBytes = options.maxObjectBytes ?? DEFAULT_MAX_OBJECT_BYTES;
+    this.threshold = options.simpleUploadThresholdBytes ?? DEFAULT_UPLOAD_THRESHOLD_BYTES;
+  }
+  capabilities() {
+    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
+  }
+  file(name) {
+    return this.storage.bucket(this.bucket).file(name);
+  }
+  async putImmutable(key, write) {
+    const objectName = storageObjectName(this.prefix, key);
+    const sink = new GcsUploadSink(this.file(objectName), this.maxObjectBytes, this.threshold);
+    try {
+      await write(sink);
+      return await sink.finish();
+    } catch (err) {
+      await sink.abort();
+      if (isPreconditionFailed(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}`);
+    }
+    if (length === 0) return new Uint8Array(0);
+    const objectName = storageObjectName(this.prefix, key);
+    try {
+      const [buf] = await this.file(objectName).download({
+        start: offset,
+        end: offset + length - 1
+      });
+      if (buf.length !== length) {
+        throw new ValidationError2(
+          `range [${offset}, ${offset + length}) out of bounds (got ${buf.length}B)`
+        );
+      }
+      return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    } catch (err) {
+      throw this.mapReadError(err, key);
+    }
+  }
+  async getTail(key, maxBytes) {
+    const objectName = storageObjectName(this.prefix, key);
+    try {
+      const [meta] = await this.file(objectName).getMetadata();
+      const size = Number(meta.size ?? 0);
+      if (!Number.isSafeInteger(size) || size < 0) {
+        throw new ValidationError2(`GCS returned an invalid object size: ${String(meta.size)}`);
+      }
+      if (maxBytes <= 0 || size === 0) return { bytes: new Uint8Array(0), size };
+      const start = Math.max(0, size - maxBytes);
+      const [buf] = await this.file(objectName).download({ start, end: size - 1 });
+      return { bytes: new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength), size };
+    } catch (err) {
+      throw this.mapReadError(err, key);
+    }
+  }
+  async delete(key) {
+    try {
+      await this.file(storageObjectName(this.prefix, key)).delete({ ignoreNotFound: true });
+    } catch (err) {
+      throw this.mapError(err);
+    }
+  }
+  async *list(ref) {
+    const prefix = segmentObjectPrefix(this.prefix, ref);
+    let files;
+    try {
+      [files] = await this.storage.bucket(this.bucket).getFiles({ prefix });
+    } catch (err) {
+      throw this.mapError(err);
+    }
+    for (const f of files) {
+      const generation = parseGenerationFromName(prefix, f.name);
+      if (generation !== null) {
+        yield { namespace: ref.namespace, segment: ref.segment, generation };
+      }
+    }
+  }
+  /** Map GCS 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 GCS 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-call site, so callers + the decorator only ever see typed errors.
+   */
+  mapError(err) {
+    if (isTransient(err)) {
+      return new TransientError(
+        `transient GCS fault: ${err?.code ?? "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 GcsUploadSink = class _GcsUploadSink {
+  constructor(file, maxObjectBytes, threshold) {
+    this.file = file;
+    this.maxObjectBytes = maxObjectBytes;
+    this.threshold = threshold;
+  }
+  file;
+  maxObjectBytes;
+  threshold;
+  hash = createHash("sha256");
+  total = 0;
+  buffered = [];
+  bufferedLen = 0;
+  stream;
+  // set once we cross the threshold → resumable mode
+  done;
+  failure;
+  static WRITE_OPTS = {
+    preconditionOpts: { ifGenerationMatch: 0 },
+    // write-once: create only if absent
+    metadata: { contentType: "application/octet-stream" }
+  };
+  async write(bytes) {
+    if (this.failure !== void 0) throw this.failure;
+    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);
+    if (this.stream !== void 0) {
+      if (!this.stream.write(bytes)) await once(this.stream, "drain");
+      return;
+    }
+    this.buffered.push(bytes);
+    this.bufferedLen += bytes.length;
+    if (this.bufferedLen > this.threshold) this.startResumable();
+  }
+  /** Cross into resumable streaming: open the stream, flush the buffered bytes, keep only ~one threshold resident. */
+  startResumable() {
+    const stream = this.file.createWriteStream({ resumable: true, ..._GcsUploadSink.WRITE_OPTS });
+    this.stream = stream;
+    this.done = once(stream, "finish");
+    stream.on("error", (e) => {
+      this.failure ??= e;
+    });
+    this.done.catch(() => void 0);
+    const buf = concatBytes(this.buffered, this.bufferedLen);
+    this.buffered.length = 0;
+    this.bufferedLen = 0;
+    stream.write(buf);
+  }
+  async finish() {
+    if (this.failure !== void 0) throw this.failure;
+    const sha256 = this.hash.digest("hex");
+    if (this.stream === void 0) {
+      await this.file.save(concatBytes(this.buffered, this.bufferedLen), {
+        resumable: false,
+        ..._GcsUploadSink.WRITE_OPTS
+      });
+      return { size: this.total, sha256 };
+    }
+    this.stream.end();
+    await this.done;
+    return { size: this.total, sha256 };
+  }
+  async abort() {
+    if (this.stream !== void 0 && !this.stream.destroyed) this.stream.destroy();
+  }
+};
+
+// src/registry.ts
+import {
+  IntegrityError,
+  MAX_ROW_BYTES,
+  ObjectStoreRegistry,
+  ObjectVersionRaced,
+  TransientError as TransientError2,
+  WriteConflictError as WriteConflictError2,
+  normalizeObjectPrefix
+} from "@cloudbitmaps/core/driver-kit";
+var GcsStore = class {
+  constructor(storage, bucket) {
+    this.storage = storage;
+    this.bucket = bucket;
+  }
+  storage;
+  bucket;
+  label = "GCS";
+  /** A file handle, optionally pinned to one object generation (GCS's version fence). */
+  file(name, generation) {
+    return generation === void 0 ? this.storage.bucket(this.bucket).file(name) : this.storage.bucket(this.bucket).file(name, { generation });
+  }
+  async read(key) {
+    let generation;
+    let size;
+    try {
+      const [meta] = await this.file(key).getMetadata();
+      generation = String(meta.generation ?? "");
+      size = Number(meta.size ?? 0);
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw mapError(err);
+    }
+    if (size > MAX_ROW_BYTES) {
+      throw new IntegrityError(`registry object ${size}B exceeds cap ${MAX_ROW_BYTES}B`);
+    }
+    try {
+      const [buf] = await this.file(key, generation).download();
+      return { bytes: new Uint8Array(buf), version: generation };
+    } catch (err) {
+      if (isNotFound(err)) throw new ObjectVersionRaced(key);
+      throw mapError(err);
+    }
+  }
+  async write(key, body, expect) {
+    try {
+      await this.file(key).save(Buffer.from(body), {
+        contentType: "application/json",
+        // `resumable: false` is load-bearing, not a tuning knob. `save()` otherwise opens a resumable
+        // session, and a registry row is a few hundred bytes — one round trip's worth of data carried over
+        // two. It also costs the fence: fake-gcs-server does not enforce `ifGenerationMatch` on the
+        // resumable path, so the whole integration lane would pass over a registry with no
+        // compare-and-swap at all. `GcsStorageDriver` pins the same flag for the same reason.
+        resumable: false,
+        preconditionOpts: {
+          ifGenerationMatch: expect === "absent" ? 0 : generationFence(expect.version, key)
+        }
+      });
+    } catch (err) {
+      if (isPreconditionFailed(err)) {
+        throw new WriteConflictError2(`registry OCC conflict for ${key}`);
+      }
+      throw mapError(err);
+    }
+  }
+  async *listKeys(prefix) {
+    let pageToken;
+    do {
+      let files;
+      let next;
+      try {
+        [files, next] = await this.storage.bucket(this.bucket).getFiles({ prefix, autoPaginate: false, maxResults: 1e3, pageToken });
+      } catch (err) {
+        throw mapError(err);
+      }
+      for (const f of files ?? []) yield f.name;
+      pageToken = next?.pageToken;
+    } while (pageToken !== void 0);
+  }
+};
+function generationFence(version, key) {
+  const generation = Number(version);
+  if (!Number.isSafeInteger(generation) || generation <= 0) {
+    throw new IntegrityError(`registry version fence is not a GCS generation: ${key}`);
+  }
+  return generation;
+}
+function mapError(err) {
+  if (isTransient(err)) {
+    return new TransientError2(
+      `transient GCS fault: ${err?.name ?? "unknown"}`,
+      { cause: err }
+    );
+  }
+  return err;
+}
+var GcsRegistryDriver = class extends ObjectStoreRegistry {
+  constructor(options) {
+    super(
+      new GcsStore(options.storage, options.bucket),
+      normalizeObjectPrefix(options.prefix),
+      options.now ?? (() => Date.now())
+    );
+  }
+};
+
+// src/backend.ts
+import { ValidationError as ValidationError3, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
+import { Storage as GcsClient } from "@google-cloud/storage";
+var GcsStorage = class {
+  storage;
+  registry;
+  /** The client both halves share — built here unless one was supplied. */
+  client;
+  constructor(options) {
+    if (options.storage !== void 0) {
+      throw new ValidationError3(
+        "GcsStorage takes the @google-cloud/storage client as `client`, not `storage` (which was the old GcsStorageDriver option). Rename it, or omit it and let the backend build one."
+      );
+    }
+    this.client = options.client ?? new GcsClient({
+      ...options.projectId === void 0 ? {} : { projectId: options.projectId },
+      ...options.apiEndpoint === void 0 ? {} : { apiEndpoint: options.apiEndpoint }
+    });
+    const shared = {
+      storage: this.client,
+      bucket: options.bucket,
+      ...options.prefix === void 0 ? {} : { prefix: options.prefix }
+    };
+    this.storage = new GcsStorageDriver(shared);
+    this.registry = new GcsRegistryDriver({
+      ...shared,
+      ...options.now === void 0 ? {} : { now: options.now }
+    });
+    brandAsBackend(this);
+  }
+};
+export {
+  GcsRegistryDriver,
+  GcsStorage,
+  GcsStorageDriver
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/storage.ts", "../src/keys.ts", "../src/gcs-errors.ts", "../src/registry.ts", "../src/backend.ts"],
+  "sourcesContent": ["/**\n * `GcsStorageDriver` \u2014 an {@link IStorageDriver} over Google Cloud Storage.\n *\n * Uses the official `@google-cloud/storage`, a real dependency of this package \u2014 installing\n * `@cloudbitmaps/gcs` is what installs it. The `Storage` client is **injected** (dependency injection): the driver owns\n * no credential/project/endpoint logic, so it's thin, reuses the caller's client, and is testable against the\n * `fake-gcs-server` emulator (point a `Storage` at its `apiEndpoint`).\n *\n * Generations are write-once immutable objects: a resumable upload with the **`ifGenerationMatch: 0`**\n * precondition (\"create only if it does not exist\") makes the publish atomic \u2014 a second write to the same\n * object fails with 412 \u2192 {@link WriteConflictError}, never a silent overwrite (hard invariant 2: storage\n * objects are immutable and never overwritten in place), the GCS analogue of S3's `If-None-Match: *` and\n * LocalFs's atomic `link`. **Writes stream in constant memory:** the codec's bytes are\n * piped into a GCS resumable-upload `Writable` (chunked/freed by the SDK as they go), so a load's write\n * footprint stays bounded regardless of segment size, up to the advertised `maxObjectBytes`. Drivers may use\n * `node:crypto`; only `core/` 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 type { Writable } from 'node:stream';\nimport { once } from 'node:events';\nimport type { Storage } from '@google-cloud/storage';\nimport {\n  storageObjectName,\n  normalizeGcsPrefix,\n  parseGenerationFromName,\n  segmentObjectPrefix,\n} from './keys';\nimport { isInvalidRange, isNotFound, isPreconditionFailed, isTransient } from './gcs-errors';\n\n/** Default object ceiling: GCS's 5 TiB per-object hard max. Set lower to fail fast on a runaway write. */\nconst DEFAULT_MAX_OBJECT_BYTES = 5 * 1024 * 1024 * 1024 * 1024;\n\n/**\n * Objects at/under this size are uploaded in a **single simple (non-resumable) request**; larger ones switch to\n * a **resumable stream** (constant memory). Mirrors S3's single-PUT-vs-multipart split \u2014 the simple path buffers\n * only \u2264 this many bytes, the resumable path streams. Default 8 MiB (\u2248 S3's part size), so peak write memory is\n * ~one threshold's worth regardless of object size.\n */\nconst DEFAULT_UPLOAD_THRESHOLD_BYTES = 8 * 1024 * 1024;\n\nexport interface GcsStorageDriverOptions {\n  /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */\n  readonly storage: Storage;\n  /** Target bucket (must already exist). */\n  readonly bucket: string;\n  /** Optional object-name prefix under which all objects live (e.g. `cloudroaring/`). */\n  readonly prefix?: string;\n  /** Largest object this driver will write/advertise (default = GCS's 5 TiB max). */\n  readonly maxObjectBytes?: number;\n  /** Bytes at/under which a single non-resumable upload is used instead of a resumable stream (default 8 MiB). */\n  readonly simpleUploadThresholdBytes?: number;\n}\n\nexport class GcsStorageDriver implements IStorageDriver {\n  private readonly storage: Storage;\n  private readonly bucket: string;\n  private readonly prefix: string | undefined;\n  private readonly maxObjectBytes: number;\n  private readonly threshold: number;\n\n  constructor(options: GcsStorageDriverOptions) {\n    this.storage = options.storage;\n    this.bucket = options.bucket;\n    this.prefix = normalizeGcsPrefix(options.prefix);\n    this.maxObjectBytes = options.maxObjectBytes ?? DEFAULT_MAX_OBJECT_BYTES;\n    this.threshold = options.simpleUploadThresholdBytes ?? DEFAULT_UPLOAD_THRESHOLD_BYTES;\n  }\n\n  capabilities(): StorageCaps {\n    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };\n  }\n\n  private file(name: string) {\n    return this.storage.bucket(this.bucket).file(name);\n  }\n\n  async putImmutable(\n    key: GenKey,\n    write: (sink: BlobSink) => Promise<void>,\n  ): Promise<{ size: number; sha256: string }> {\n    const objectName = storageObjectName(this.prefix, key); // validates ref + generation\n    const sink = new GcsUploadSink(this.file(objectName), this.maxObjectBytes, this.threshold);\n    try {\n      await write(sink);\n      return await sink.finish();\n    } catch (err) {\n      await sink.abort(); // best-effort teardown of the in-flight upload\n      // A lost write-once race \u2014 the object already existed, so `ifGenerationMatch: 0` failed with 412.\n      if (isPreconditionFailed(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)) throw err;\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    if (length === 0) return new Uint8Array(0);\n    const objectName = storageObjectName(this.prefix, key);\n    try {\n      // GCS `end` is inclusive.\n      const [buf] = await this.file(objectName).download({\n        start: offset,\n        end: offset + length - 1,\n      });\n      // A short read means the range ran past EOF \u2014 treat as out-of-bounds, never a partial result.\n      if (buf.length !== length) {\n        throw new ValidationError(\n          `range [${offset}, ${offset + length}) out of bounds (got ${buf.length}B)`,\n        );\n      }\n      return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);\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 objectName = storageObjectName(this.prefix, key);\n    try {\n      // Two round-trips (metadata for the size, then a ranged download) vs S3's one (suffix-range +\n      // Content-Range). This is on the per-*generation* open path, which the reader caches \u2014 NOT the per-op cache\n      // path (add/has/count/intersect) \u2014 so it's amortized; collapsing to one RT is a tracked follow-up.\n      const [meta] = await this.file(objectName).getMetadata();\n      const size = Number(meta.size ?? 0);\n      if (!Number.isSafeInteger(size) || size < 0) {\n        throw new ValidationError(`GCS returned an invalid object size: ${String(meta.size)}`);\n      }\n      if (maxBytes <= 0 || size === 0) return { bytes: new Uint8Array(0), size };\n      const start = Math.max(0, size - maxBytes);\n      const [buf] = await this.file(objectName).download({ start, end: size - 1 });\n      return { bytes: new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength), size };\n    } catch (err) {\n      throw this.mapReadError(err, key);\n    }\n  }\n\n  async delete(key: GenKey): Promise<void> {\n    // Idempotent: `ignoreNotFound` so a racing/retried GC sweep of an absent object is a no-op.\n    try {\n      await this.file(storageObjectName(this.prefix, key)).delete({ ignoreNotFound: true });\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 files;\n    try {\n      // autoPaginate (default) drains every page; a segment has few generations, so the set is small.\n      [files] = await this.storage.bucket(this.bucket).getFiles({ prefix });\n    } catch (err) {\n      throw this.mapError(err);\n    }\n    for (const f of files) {\n      const generation = parseGenerationFromName(prefix, f.name);\n      if (generation !== null) {\n        yield { namespace: ref.namespace, segment: ref.segment, generation };\n      }\n    }\n  }\n\n  /** Map GCS 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    // 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 GCS 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-call site, so callers + the decorator only ever see typed errors.\n   */\n  private mapError(err: unknown): unknown {\n    if (isTransient(err)) {\n      return new TransientError(\n        `transient GCS fault: ${(err as { code?: unknown } | null)?.code ?? 'unknown'}`,\n        { cause: err },\n      );\n    }\n    return err;\n  }\n}\n\ntype GcsFile = ReturnType<ReturnType<Storage['bucket']>['file']>;\n\n/** Concatenate 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 * {@link BlobSink} that uploads one GCS object write-once. It **buffers up to a threshold**: an object that\n * finishes at/under it is committed in a **single simple (non-resumable) request** (`file.save`) \u2014 the write-once\n * path both real GCS and `fake-gcs-server` enforce; a larger one switches to a **resumable stream**, flushing the\n * buffer then piping the rest in constant memory (peak \u2248 one threshold). SHA-256 is hashed incrementally. Both\n * paths carry `ifGenerationMatch: 0` (create-only-if-absent) \u2192 a conflict is a 412, mapped by the driver to\n * {@link WriteConflictError}. On error the caller invokes {@link abort}.\n */\nclass GcsUploadSink implements BlobSink {\n  private readonly hash: Hash = createHash('sha256');\n  private total = 0;\n  private readonly buffered: Uint8Array[] = [];\n  private bufferedLen = 0;\n  private stream: Writable | undefined; // set once we cross the threshold \u2192 resumable mode\n  private done: Promise<unknown[]> | undefined;\n  private failure: unknown;\n\n  constructor(\n    private readonly file: GcsFile,\n    private readonly maxObjectBytes: number,\n    private readonly threshold: number,\n  ) {}\n\n  private static readonly WRITE_OPTS = {\n    preconditionOpts: { ifGenerationMatch: 0 as const }, // write-once: create only if absent\n    metadata: { contentType: 'application/octet-stream' },\n  };\n\n  async write(bytes: Uint8Array): Promise<void> {\n    if (this.failure !== undefined) throw this.failure;\n    if (bytes.length === 0) return;\n    this.total += bytes.length;\n    if (this.total > this.maxObjectBytes) {\n      throw new ValidationError(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);\n    }\n    this.hash.update(bytes);\n    if (this.stream !== undefined) {\n      // Resumable mode: honor backpressure. `events.once(stream,'drain')` REJECTS if the stream emits 'error'\n      // while we wait (that's its documented behavior for any awaited event except 'error'), and auto-removes\n      // both listeners on settle \u2014 so there's no listener accumulation across drain cycles.\n      if (!this.stream.write(bytes)) await once(this.stream, 'drain');\n      return;\n    }\n    this.buffered.push(bytes);\n    this.bufferedLen += bytes.length;\n    if (this.bufferedLen > this.threshold) this.startResumable();\n  }\n\n  /** Cross into resumable streaming: open the stream, flush the buffered bytes, keep only ~one threshold resident. */\n  private startResumable(): void {\n    const stream = this.file.createWriteStream({ resumable: true, ...GcsUploadSink.WRITE_OPTS });\n    this.stream = stream;\n    this.done = once(stream, 'finish'); // resolves on a clean commit; rejects on 'error' (e.g. 412)\n    stream.on('error', (e: unknown) => {\n      this.failure ??= e; // a persistent listener so a stray 'error' is never an unhandled 'error' event\n    });\n    this.done.catch(() => undefined); // finish() awaits this; guard against unhandled rejection until then\n    const buf = concatBytes(this.buffered, this.bufferedLen);\n    this.buffered.length = 0;\n    this.bufferedLen = 0;\n    stream.write(buf); // \u2264 threshold+one-chunk; backpressure is absorbed by the next write()'s drain-await / end()\n  }\n\n  async finish(): Promise<{ size: number; sha256: string }> {\n    if (this.failure !== undefined) throw this.failure;\n    const sha256 = this.hash.digest('hex');\n    if (this.stream === undefined) {\n      // Small object: a single simple (non-resumable) upload \u2014 write-once enforced everywhere (incl. the emulator).\n      await this.file.save(concatBytes(this.buffered, this.bufferedLen), {\n        resumable: false,\n        ...GcsUploadSink.WRITE_OPTS,\n      });\n      return { size: this.total, sha256 };\n    }\n    this.stream.end();\n    await this.done; // rejects if the commit fails (e.g. 412 write-once conflict)\n    return { size: this.total, sha256 };\n  }\n\n  async abort(): Promise<void> {\n    if (this.stream !== undefined && !this.stream.destroyed) this.stream.destroy();\n  }\n}\n", "/**\n * Logical-ref \u2192 GCS object-name mapping for {@link GcsStorageDriver}.\n *\n * Pure string logic, no SDK dependency \u2014 unit-testable without GCS or an emulator. Uses the **same\n * backend-agnostic `.crbm` object-name scheme** as the S3 + LocalFs storage drivers\n * (`<prefix><ns>/segments/<segment>.<gen>.crbm`), so a segment reads identically whichever storage backend holds\n * it. The default (absent) namespace maps to `_default`, which cannot collide with a real namespace because a\n * caller's `_default` encodes to `%5Fdefault` while the sentinel is emitted literally.\n *\n * The storage-key layout is shared, not copied: `prefixPart` and the name encoders come from\n * `@cloudbitmaps/core/driver-kit`, so a segment written by one driver reads identically under another. Two\n * drivers disagreeing about how a name becomes a key would be a silent cross-driver incompatibility on the\n * same bucket, which is exactly the kind of thing a local copy drifts into.\n */\n\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/**\n * Validate the caller-supplied key prefix (trusted config, but a real containment boundary): reject control\n * characters and `.`/`..` path segments so a prefix can't traverse out of its intended space. Returns it\n * unchanged (the key builders normalize slashes).\n */\nexport function normalizeGcsPrefix(prefix: string | undefined): string | undefined {\n  if (prefix === undefined) return undefined;\n  for (const ch of prefix) {\n    if (ch.charCodeAt(0) < 0x20) {\n      throw new ValidationError('prefix must not contain control characters');\n    }\n  }\n  for (const segment of prefix.split('/')) {\n    if (segment === '.' || segment === '..') {\n      throw new ValidationError(\n        `prefix must not contain \".\" or \"..\" path segments: ${JSON.stringify(prefix)}`,\n      );\n    }\n  }\n  return prefix;\n}\n\n/**\n * The GCS object-name prefix shared by all of a segment's generations: `<prefix><ns>/segments/<segment>.`.\n * Used both as the `getFiles` prefix and as the string stripped by {@link parseGenerationFromName}.\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 GCS object name of one `.crbm` generation: `<segmentPrefix><gen>.crbm`. */\nexport function storageObjectName(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/**\n * Parse a generation number out of a full object name, 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. Also rejects a *different* segment whose name merely shares the prefix (its middle\n * isn't all digits).\n */\nexport function parseGenerationFromName(segmentPrefix: string, objectName: string): number | null {\n  if (!objectName.startsWith(segmentPrefix) || !objectName.endsWith(SUFFIX)) return null;\n  const middle = objectName.slice(segmentPrefix.length, objectName.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 Google Cloud Storage SDK errors (the transient class mirrors S3's).\n *\n * SDK-free + side-effect-free \u2014 they only read structural shapes off the thrown value (`err.code`,\n * `err.response.status`, `err.name`), so the GCS-specific translation is unit-testable without a live GCS or\n * an emulator, and without importing `@google-cloud/storage`. GCS's `ApiError` carries the HTTP status on\n * `.code` (a number); dropped/timed-out sockets surface as a Node error with a string `.code` (`ECONNRESET`,\n * `ETIMEDOUT`, \u2026).\n */\n\n/** The HTTP status of a GCS `ApiError`, if present (`err.code` as a number, or `err.response.status`). */\nfunction httpStatus(err: unknown): number | undefined {\n  const e = err as { code?: unknown; response?: { status?: unknown } } | null;\n  if (typeof e?.code === 'number') return e.code;\n  if (typeof e?.response?.status === 'number') return e.response.status;\n  return undefined;\n}\n\n/** A network-level error `code` string (e.g. `ECONNRESET`, `ETIMEDOUT`, `EAI_AGAIN`, `EPIPE`). */\nfunction networkCode(err: unknown): string | undefined {\n  const code = (err as { code?: unknown } | null)?.code;\n  return typeof code === 'string' ? code : undefined;\n}\n\n/**\n * A conditional `ifGenerationMatch: 0` write lost the write-once race \u2014 the object already existed, so GCS\n * returns **412 Precondition Failed**. Maps to `WriteConflictError` (caller OCC), never a blind retry.\n */\nexport function isPreconditionFailed(err: unknown): boolean {\n  return httpStatus(err) === 412;\n}\n\n/** The object / generation does not exist (GCS returns 404). */\nexport function isNotFound(err: unknown): boolean {\n  return httpStatus(err) === 404;\n}\n\n/** A range request started past EOF (HTTP 416 Requested Range Not Satisfiable). */\nexport function isInvalidRange(err: unknown): boolean {\n  return httpStatus(err) === 416;\n}\n\n/**\n * A transient GCS fault that is safe to retry: throttling (429), any 5xx, or a dropped/timed-out socket.\n * Excludes the deterministic, caller-meaningful outcomes (412/404/416) \u2014 those must never be reclassified as\n * a blind transient (a retried doomed conditional write would just fail again, and mask an OCC conflict).\n */\nexport function isTransient(err: unknown): boolean {\n  if (isPreconditionFailed(err) || isNotFound(err) || isInvalidRange(err)) return false;\n  const status = httpStatus(err);\n  if (status === 429 || (status !== undefined && status >= 500 && status < 600)) return true;\n  const net = networkCode(err);\n  return (\n    net === 'ECONNRESET' ||\n    net === 'ETIMEDOUT' ||\n    net === 'ECONNREFUSED' ||\n    net === 'EPIPE' ||\n    net === 'EAI_AGAIN' ||\n    net === 'ENOTFOUND'\n  );\n}\n", "/**\n * `GcsRegistryDriver` \u2014 an {@link IRegistryDriver} over Google Cloud Storage.\n *\n * Lets a **GCS deployment run on one bucket alone** \u2014 storage `.crbm` generations and the registry in the same\n * place, with no second cloud involved. Before this existed, a GCS user had to point the registry at a\n * separate AWS-hosted table, which meant holding an AWS account purely to store the pointer that says which\n * generation is current.\n *\n * The protocol (an ABA-safe OCC counter, tombstoning delete, the bounded retry, the key layout) lives once\n * in {@link ObjectStoreRegistry}; this file is only the three I/O calls GCS makes.\n *\n * **The atomic swap is offloaded to GCS's object preconditions.** `ifGenerationMatch: 0` is create-only\n * (\"only if it does not exist\") and `ifGenerationMatch: <generation>` is compare-and-swap \u2014 the same pair S3\n * spells `If-None-Match: *` / `If-Match: <etag>`. A lost race returns `412` \u2192 {@link WriteConflictError}.\n * **The version fence is the object's `generation`, not its ETag**: GCS mutates the generation on every\n * overwrite and it is the value `ifGenerationMatch` compares, so it is the only correct fence here. (Note\n * the unrelated collision of vocabulary \u2014 a GCS *object generation* has nothing to do with a CloudBitmaps\n * `.crbm` *generation*.) Reads are strongly consistent, satisfying the registry's `strongRead` contract.\n *\n * **Deployment requirements** (a policy that violates these silently corrupts the registry):\n * - The principal needs `storage.objects.get`, `create`, `update` and `list` on the bucket. Without `list`\n *   the registry cannot enumerate, and a missing-object read may surface as `403` rather than `404`.\n * - **Do not apply an Object Lifecycle rule to the `registry/` prefix**, and do not enable a retention\n *   policy that blocks overwrite. `delete` tombstones rather than removing, for ABA-safety \u2014 see\n *   {@link ObjectStoreRegistry}.\n * - Object versioning is neither required nor used; the driver always reads the live generation. Because a\n *   non-versioned bucket retires a superseded generation immediately, a read whose pinned generation is\n *   overwritten mid-flight reports {@link ObjectVersionRaced} and is retried by {@link ObjectStoreRegistry},\n *   never mistaken for an absent row.\n */\nimport {\n  IntegrityError,\n  MAX_ROW_BYTES,\n  ObjectStoreRegistry,\n  ObjectVersionRaced,\n  TransientError,\n  WriteConflictError,\n  normalizeObjectPrefix,\n} from '@cloudbitmaps/core/driver-kit';\nimport type { ObjectRegistryStore, ObjectRow } from '@cloudbitmaps/core/driver-kit';\nimport type { Storage } from '@google-cloud/storage';\nimport { isNotFound, isPreconditionFailed, isTransient } from './gcs-errors';\n\nexport interface GcsRegistryDriverOptions {\n  /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */\n  readonly storage: Storage;\n  /** Target bucket (must already exist). */\n  readonly bucket: string;\n  /** Optional object-name 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 GCS's dialect. */\nclass GcsStore implements ObjectRegistryStore {\n  readonly label = 'GCS';\n\n  constructor(\n    private readonly storage: Storage,\n    private readonly bucket: string,\n  ) {}\n\n  /** A file handle, optionally pinned to one object generation (GCS's version fence). */\n  private file(name: string, generation?: string) {\n    return generation === undefined\n      ? this.storage.bucket(this.bucket).file(name)\n      : this.storage.bucket(this.bucket).file(name, { generation });\n  }\n\n  async read(key: string): Promise<ObjectRow | null> {\n    // Metadata first: it carries the `generation` fence AND the size, so a hostile object is rejected on its\n    // advertised length before any of it is buffered.\n    let generation: string;\n    let size: number;\n    try {\n      const [meta] = await this.file(key).getMetadata();\n      generation = String(meta.generation ?? '');\n      size = Number(meta.size ?? 0);\n    } catch (err) {\n      if (isNotFound(err)) return null;\n      throw mapError(err);\n    }\n    if (size > MAX_ROW_BYTES) {\n      throw new IntegrityError(`registry object ${size}B exceeds cap ${MAX_ROW_BYTES}B`);\n    }\n    try {\n      // Pin the download to the generation we just measured, so a concurrent overwrite between the two calls\n      // cannot hand us bytes that do not match the fence we are about to compare-and-swap against.\n      const [buf] = await this.file(key, generation).download();\n      return { bytes: new Uint8Array(buf), version: generation };\n    } catch (err) {\n      // A 404 on the PINNED download does not mean the object is gone \u2014 it means the generation we pinned\n      // is. Buckets here run without Object Versioning (the registry neither needs nor uses it), so an\n      // overwrite retires the superseded generation immediately and this is simply what losing the pin looks\n      // like. Reporting it as absence would make a live row disappear from `get`, hand `delete` a false\n      // success, and silently drop rows from `list`; the caller re-reads instead.\n      if (isNotFound(err)) throw new ObjectVersionRaced(key);\n      throw mapError(err);\n    }\n  }\n\n  async write(\n    key: string,\n    body: Uint8Array,\n    expect: 'absent' | { version: string },\n  ): Promise<void> {\n    try {\n      await this.file(key).save(Buffer.from(body), {\n        contentType: 'application/json',\n        // `resumable: false` is load-bearing, not a tuning knob. `save()` otherwise opens a resumable\n        // session, and a registry row is a few hundred bytes \u2014 one round trip's worth of data carried over\n        // two. It also costs the fence: fake-gcs-server does not enforce `ifGenerationMatch` on the\n        // resumable path, so the whole integration lane would pass over a registry with no\n        // compare-and-swap at all. `GcsStorageDriver` pins the same flag for the same reason.\n        resumable: false,\n        preconditionOpts: {\n          ifGenerationMatch: expect === 'absent' ? 0 : generationFence(expect.version, key),\n        },\n      });\n    } catch (err) {\n      if (isPreconditionFailed(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 pageToken: string | undefined;\n    do {\n      let files;\n      let next: { pageToken?: string } | null | undefined;\n      try {\n        // Explicit paging rather than autoPaginate: a registry can hold far more rows than a segment holds\n        // generations, and draining every page into memory first is what `list()` exists to avoid.\n        [files, next] = await this.storage\n          .bucket(this.bucket)\n          .getFiles({ prefix, autoPaginate: false, maxResults: 1000, pageToken });\n      } catch (err) {\n        throw mapError(err);\n      }\n      for (const f of files ?? []) yield f.name;\n      pageToken = next?.pageToken;\n    } while (pageToken !== undefined);\n  }\n}\n\n/**\n * Narrow a version fence back to the number `ifGenerationMatch` takes. The fence always originates as\n * `meta.generation` in {@link GcsStore.read}, so this cannot fire in practice \u2014 but `Number()` answers `NaN`\n * for anything non-numeric, and `ifGenerationMatch: NaN` serializes to a precondition GCS ignores. That\n * failure is invisible (writes simply stop being fenced), so it is checked rather than assumed.\n */\nfunction generationFence(version: string, key: string): number {\n  const generation = Number(version);\n  if (!Number.isSafeInteger(generation) || generation <= 0) {\n    throw new IntegrityError(`registry version fence is not a GCS generation: ${key}`);\n  }\n  return generation;\n}\n\n/** Reclassify a transient GCS 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 GCS fault: ${(err as { name?: string } | null)?.name ?? 'unknown'}`,\n      { cause: err },\n    );\n  }\n  return err;\n}\n\nexport class GcsRegistryDriver extends ObjectStoreRegistry {\n  constructor(options: GcsRegistryDriverOptions) {\n    super(\n      new GcsStore(options.storage, options.bucket),\n      normalizeObjectPrefix(options.prefix),\n      options.now ?? ((): number => Date.now()),\n    );\n  }\n}\n", "/**\n * `GcsStorage` \u2014 the Google Cloud Storage backend as one object: generations and pointer, one bucket, stated once.\n *\n * See {@link StorageBackend} for why the two halves are configured together rather than separately.\n *\n * **A note on the word.** `@google-cloud/storage` names its own client class `Storage`, so the driver option\n * that takes it is also called `storage` \u2014 which, since our durable tier is now called storage too, reads as\n * the same word meaning two things. That is why this class builds the client itself: `new GcsStorage({ bucket })`\n * never makes you write `{ storage: storage }`. Supply `client` when you need your own.\n */\nimport { STORAGE_BACKEND, ValidationError, brandAsBackend } from '@cloudbitmaps/core/driver-kit';\nimport type {\n  IRegistryDriver,\n  IStorageDriver,\n  StorageBackend,\n} from '@cloudbitmaps/core/driver-kit';\nimport { Storage as GcsClient } from '@google-cloud/storage';\nimport { GcsStorageDriver } from './storage';\nimport { GcsRegistryDriver } from './registry';\n\nexport interface GcsStorageOptions {\n  /** Target bucket (must already exist). */\n  readonly bucket: string;\n  /** Optional object-name prefix under which everything lives \u2014 generations and the registry alike. */\n  readonly prefix?: string;\n  /** A constructed `@google-cloud/storage` client. One is built from the ambient credentials when absent. */\n  readonly client?: GcsClient;\n  /**\n   * Not an option \u2014 the old `GcsStorageDriver` took the client as `storage`, and a migrating caller keeps the\n   * name. Typed `never` so the object literal is a compile error, and rejected at runtime for JavaScript\n   * callers, because silently ignoring it falls back to ambient credentials and the **public** endpoint: for\n   * anyone whose client pointed at an emulator, that is production traffic from a wiring typo.\n   */\n  readonly storage?: never;\n  /** Project id for the client built when `client` is absent. Falls back to the SDK's own resolution. */\n  readonly projectId?: string;\n  /** Endpoint override \u2014 point it at fake-gcs-server locally. Ignored when `client` is supplied. */\n  readonly apiEndpoint?: string;\n  /** Injected clock for the registry's `createdAt`/`updatedAt`; defaults to `Date.now`. */\n  readonly now?: () => number;\n}\n\nexport class GcsStorage 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: GcsClient;\n\n  constructor(options: GcsStorageOptions) {\n    if ((options as { storage?: unknown }).storage !== undefined) {\n      throw new ValidationError(\n        'GcsStorage takes the @google-cloud/storage client as `client`, not `storage` (which was the old ' +\n          'GcsStorageDriver option). Rename it, or omit it and let the backend build one.',\n      );\n    }\n    this.client =\n      options.client ??\n      new GcsClient({\n        ...(options.projectId === undefined ? {} : { projectId: options.projectId }),\n        ...(options.apiEndpoint === undefined ? {} : { apiEndpoint: options.apiEndpoint }),\n      });\n    const shared = {\n      storage: this.client,\n      bucket: options.bucket,\n      ...(options.prefix === undefined ? {} : { prefix: options.prefix }),\n    };\n    this.storage = new GcsStorageDriver(shared);\n    this.registry = new GcsRegistryDriver({\n      ...shared,\n      ...(options.now === undefined ? {} : { now: options.now }),\n    });\n    brandAsBackend(this);\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["ValidationError", "ValidationError", "TransientError", "WriteConflictError", "WriteConflictError", "TransientError", "ValidationError", "ValidationError"]
+}

package/dist/keys.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Logical-ref → GCS object-name mapping for {@link GcsStorageDriver}.
+ *
+ * Pure string logic, no SDK dependency — unit-testable without GCS or an emulator. Uses the **same
+ * backend-agnostic `.crbm` object-name scheme** as the S3 + LocalFs storage drivers
+ * (`<prefix><ns>/segments/<segment>.<gen>.crbm`), so a segment reads identically whichever storage backend holds
+ * it. The default (absent) namespace maps to `_default`, which cannot collide with a real namespace because a
+ * caller's `_default` encodes to `%5Fdefault` while the sentinel is emitted literally.
+ *
+ * The storage-key layout is shared, not copied: `prefixPart` and the name encoders come from
+ * `@cloudbitmaps/core/driver-kit`, so a segment written by one driver reads identically under another. Two
+ * drivers disagreeing about how a name becomes a key would be a silent cross-driver incompatibility on the
+ * same bucket, which is exactly the kind of thing a local copy drifts into.
+ */
+import type { GenKey, SegmentRef } from '@cloudbitmaps/core/driver-kit';
+/**
+ * Validate the caller-supplied key prefix (trusted config, but a real containment boundary): reject control
+ * characters and `.`/`..` path segments so a prefix can't traverse out of its intended space. Returns it
+ * unchanged (the key builders normalize slashes).
+ */
+export declare function normalizeGcsPrefix(prefix: string | undefined): string | undefined;
+/**
+ * The GCS object-name prefix shared by all of a segment's generations: `<prefix><ns>/segments/<segment>.`.
+ * Used both as the `getFiles` prefix and as the string stripped by {@link parseGenerationFromName}.
+ */
+export declare function segmentObjectPrefix(prefix: string | undefined, ref: SegmentRef): string;
+/** The full GCS object name of one `.crbm` generation: `<segmentPrefix><gen>.crbm`. */
+export declare function storageObjectName(prefix: string | undefined, key: GenKey): string;
+/**
+ * Parse a generation number out of a full object name, 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. Also rejects a *different* segment whose name merely shares the prefix (its middle
+ * isn't all digits).
+ */
+export declare function parseGenerationFromName(segmentPrefix: string, objectName: string): number | null;

package/dist/registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `GcsRegistryDriver` — an {@link IRegistryDriver} over Google Cloud Storage.
+ *
+ * Lets a **GCS deployment run on one bucket alone** — storage `.crbm` generations and the registry in the same
+ * place, with no second cloud involved. Before this existed, a GCS user had to point the registry at a
+ * separate AWS-hosted table, which meant holding an AWS account purely to store the pointer that says which
+ * generation is current.
+ *
+ * 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 GCS makes.
+ *
+ * **The atomic swap is offloaded to GCS's object preconditions.** `ifGenerationMatch: 0` is create-only
+ * ("only if it does not exist") and `ifGenerationMatch: <generation>` is compare-and-swap — the same pair S3
+ * spells `If-None-Match: *` / `If-Match: <etag>`. A lost race returns `412` → {@link WriteConflictError}.
+ * **The version fence is the object's `generation`, not its ETag**: GCS mutates the generation on every
+ * overwrite and it is the value `ifGenerationMatch` compares, so it is the only correct fence here. (Note
+ * the unrelated collision of vocabulary — a GCS *object generation* has nothing to do with a CloudBitmaps
+ * `.crbm` *generation*.) Reads are strongly consistent, satisfying the registry's `strongRead` contract.
+ *
+ * **Deployment requirements** (a policy that violates these silently corrupts the registry):
+ * - The principal needs `storage.objects.get`, `create`, `update` and `list` on the bucket. Without `list`
+ *   the registry cannot enumerate, and a missing-object read may surface as `403` rather than `404`.
+ * - **Do not apply an Object Lifecycle rule to the `registry/` prefix**, and do not enable a retention
+ *   policy that blocks overwrite. `delete` tombstones rather than removing, for ABA-safety — see
+ *   {@link ObjectStoreRegistry}.
+ * - Object versioning is neither required nor used; the driver always reads the live generation. Because a
+ *   non-versioned bucket retires a superseded generation immediately, a read whose pinned generation is
+ *   overwritten mid-flight reports {@link ObjectVersionRaced} and is retried by {@link ObjectStoreRegistry},
+ *   never mistaken for an absent row.
+ */
+import { ObjectStoreRegistry } from '@cloudbitmaps/core/driver-kit';
+import type { Storage } from '@google-cloud/storage';
+export interface GcsRegistryDriverOptions {
+    /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */
+    readonly storage: Storage;
+    /** Target bucket (must already exist). */
+    readonly bucket: string;
+    /** Optional object-name 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 GcsRegistryDriver extends ObjectStoreRegistry {
+    constructor(options: GcsRegistryDriverOptions);
+}

package/dist/storage.d.ts

@@ -0,0 +1,43 @@
+import type { BlobSink, GenKey, IStorageDriver, SegmentRef, StorageCaps } from '@cloudbitmaps/core/driver-kit';
+import type { Storage } from '@google-cloud/storage';
+export interface GcsStorageDriverOptions {
+    /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */
+    readonly storage: Storage;
+    /** Target bucket (must already exist). */
+    readonly bucket: string;
+    /** Optional object-name prefix under which all objects live (e.g. `cloudroaring/`). */
+    readonly prefix?: string;
+    /** Largest object this driver will write/advertise (default = GCS's 5 TiB max). */
+    readonly maxObjectBytes?: number;
+    /** Bytes at/under which a single non-resumable upload is used instead of a resumable stream (default 8 MiB). */
+    readonly simpleUploadThresholdBytes?: number;
+}
+export declare class GcsStorageDriver implements IStorageDriver {
+    private readonly storage;
+    private readonly bucket;
+    private readonly prefix;
+    private readonly maxObjectBytes;
+    private readonly threshold;
+    constructor(options: GcsStorageDriverOptions);
+    capabilities(): StorageCaps;
+    private file;
+    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 GCS read errors to the driver vocabulary; pass everything else through {@link mapError}. */
+    private mapReadError;
+    /**
+     * Reclassify a transient GCS 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-call site, so callers + the decorator only ever see typed errors.
+     */
+    private mapError;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@cloudbitmaps/gcs",
+  "version": "0.10.0-rc.0",
+  "description": "Google Cloud Storage for CloudBitmaps",
+  "keywords": [
+    "cloudbitmaps",
+    "bitmap",
+    "roaring-bitmap",
+    "serverless",
+    "cloud",
+    "typescript",
+    "gcs",
+    "google-cloud",
+    "google-cloud-storage",
+    "object-storage"
+  ],
+  "license": "Apache-2.0",
+  "author": "Sharvil Kadam",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudbitmaps/cloudbitmaps.git",
+    "directory": "packages/gcs"
+  },
+  "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": {
+    "@google-cloud/storage": "^7 || ^8",
+    "@cloudbitmaps/core": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs"
+  }
+}