@cloudbitmaps/core 0.8.2 → 0.10.0

package/dist/core/retry.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `withRetry` — the one retry/backoff primitive.
+ *
+ * A pure, storage-agnostic helper: it knows nothing about HTTP, AWS, or any SDK. It retries an operation
+ * while the operation keeps failing with a **retryable** error (by default {@link TransientError}), waiting
+ * a bounded, jittered, exponentially-growing delay between attempts. Time and randomness are **injected**
+ * (the determinism seam) — production wires a `setTimeout`-backed clock + a real RNG; the
+ * tests wire virtual ones — so a backoff schedule is replayable from a seed and unit tests run with no
+ * real sleeping.
+ *
+ * It deliberately does **not** retry deterministic failures ({@link WriteConflictError},
+ * {@link ValidationError}, {@link IntegrityError}, {@link NotFoundError}, …): retrying those either can't
+ * help or would be incorrect. A pointer conflict is retried by a *separate* loop inside
+ * `publishGeneration`, because each attempt must re-read the row and re-decide — a blind replay of the same
+ * compare-and-swap would either fail again on a stale token or, worse, advance a pointer whose state has
+ * changed underneath it. A write-once object collision is never replayed at all: the generation number is
+ * taken, so the caller has to pick a new one.
+ */
+import type { Clock, Rng } from './determinism.js';
+export interface RetryPolicy {
+    /** Total attempts including the first (so `maxAttempts: 4` = 1 try + 3 retries). Must be ≥ 1. */
+    readonly maxAttempts: number;
+    /** Delay before the first retry, in ms. Grows by `backoffFactor` each subsequent retry. */
+    readonly baseDelayMs: number;
+    /** Upper bound on a single (pre-jitter) delay, in ms — caps the exponential growth. */
+    readonly maxDelayMs: number;
+    /** Exponential growth factor between retries (e.g. 2 ⇒ base, 2·base, 4·base, …). */
+    readonly backoffFactor: number;
+    /**
+     * `'full'` ⇒ the actual wait is uniform in `[0, computed]` (AWS-recommended full jitter: decorrelates
+     * concurrent retriers so they don't reconverge into a thundering herd). `'none'` ⇒ wait exactly `computed`.
+     */
+    readonly jitter: 'full' | 'none';
+}
+/**
+ * Conservative defaults: 4 attempts, 50ms → 100 → 200 (×2), capped at 2s, full jitter. Tuned for a cloud
+ * backend's brief throttle/5xx blip — enough to ride out a transient fault without turning a hard outage
+ * into a long hang. Override per store/driver if your latency budget differs.
+ */
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+export interface RetryDeps {
+    readonly clock: Clock;
+    readonly rng: Rng;
+    /** Override which errors are retryable. Default: any {@link TransientError} (incl. `TimeoutError`). */
+    readonly isRetryable?: (err: unknown) => boolean;
+    /** Optional hook (observability) fired before each backoff wait. `attempt` is 1-based (the one that failed). */
+    readonly onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        err: unknown;
+    }) => void;
+}
+/**
+ * Backoff delay (ms) for the retry that follows a given 1-based attempt, before jitter is applied. Exposed
+ * for tests. `attempt` 1 ⇒ `baseDelayMs`, 2 ⇒ `base·factor`, … capped at `maxDelayMs`.
+ */
+export declare function backoffDelayMs(policy: RetryPolicy, attempt: number): number;
+/** Apply the policy's jitter to a computed delay using the injected RNG. */
+export declare function applyJitter(policy: RetryPolicy, delayMs: number, rng: Rng): number;
+/**
+ * Run `op`, retrying transient failures per `policy`. Resolves with `op`'s result, or rejects with the last
+ * error once attempts are exhausted (or immediately for a non-retryable error). The thrown error is always
+ * the *operation's* error — never a wrapper — so callers keep their typed-error branching.
+ */
+export declare function withRetry<T>(op: () => Promise<T>, policy: RetryPolicy, deps: RetryDeps): Promise<T>;

package/dist/core/rollback.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `listGenerations` and `rollbackSegment` — see what a segment has been, and put it back.
+ *
+ * Immutable generations mean the previous version of a segment is usually still sitting in the bucket: a load
+ * that replaced it did not overwrite anything, it wrote a new object and moved a pointer. So recovering from a
+ * bad load is, in principle, moving the pointer back — and until now there was no way to do it, because every
+ * write path in the library is deliberately **forward-only** and refuses a regression.
+ *
+ * That refusal is right for a *writer*: a load whose ids came from upstream loses nothing by being out-raced, and
+ * letting it regress the pointer would let a slow loader silently undo a fast one. It is wrong for an *operator*,
+ * who has looked at the segment, decided the current generation is wrong, and knows which one they want. So
+ * rollback is the one call that moves the pointer backwards, and it is deliberately not reachable from any
+ * automatic path — no sweep, no retry, no reconciliation calls it.
+ *
+ * It is audited for the same reason. Every other pointer move can be reconstructed from "a load happened"; this
+ * one is a human overriding the ordering rule the rest of the system relies on, which is exactly the event an
+ * Art. 30 record or an incident review wants to find.
+ */
+import { type IAuditSink } from './audit.js';
+import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+/** What the generation helpers need: the objects, and the pointer that says which one is current. */
+export interface GenerationListDeps {
+    readonly storage: IStorageDriver;
+    readonly registry: IRegistryDriver;
+}
+/** One generation present in the bucket. */
+export interface GenerationEntry {
+    readonly generation: number;
+    /** Whether the registry pointer currently names this generation. */
+    readonly current: boolean;
+}
+/**
+ * Every generation still present for a segment, ascending, with the current one marked.
+ *
+ * This is what the bucket holds, not what the segment has ever been: generation collection deletes superseded
+ * objects, so the list is the grace window plus whatever has not been collected yet. It is the set a
+ * {@link rollbackSegment} can choose from, which is the reason to look at it.
+ *
+ * One `list` call. It does not open the objects, so it costs nothing per generation and tells you nothing about
+ * their contents — read the sizes through the store's own report if you need them.
+ */
+export declare function listGenerations(ref: SegmentRef, deps: GenerationListDeps): Promise<GenerationEntry[]>;
+export interface RollbackResult {
+    /** The generation the pointer named before the rollback. `null` when the segment had no current generation. */
+    readonly fromGeneration: number | null;
+    /** The generation the pointer names now. */
+    readonly generation: number;
+}
+/**
+ * Move a segment's pointer **back** to a generation that is still in the bucket.
+ *
+ * The only non-forward-only publish in the library, and the only one an operator has to ask for by name. It
+ * refuses rather than guesses:
+ *
+ * - a generation whose object is **not in the bucket** — collected, or never written — is refused with
+ *   `NotFoundError` rather than pointed at, because a pointer naming a missing object is the one state the whole
+ *   design exists to avoid;
+ * - a **crypto-shredded** segment is refused: every generation of it is unreadable, so a rollback would produce a
+ *   segment that resolves and then fails;
+ * - rolling to the generation **already current** is a no-op that reports itself, not an error.
+ *
+ * What it does **not** do is delete anything. The generations above the new pointer stay in the bucket, which is
+ * what makes the rollback reversible — roll forward again by naming one of them. They are also then *above*
+ * `currentGen`, where generation collection never looks, so they will sit there until a later load raises the
+ * pointer past them or they are deleted deliberately. That is a deliberate trade: an operator who has just
+ * undone a bad load should not have the evidence collected out from under them.
+ */
+export declare function rollbackSegment(ref: SegmentRef, toGeneration: number, deps: GenerationListDeps, options?: {
+    audit?: IAuditSink;
+    allowForward?: boolean;
+}): Promise<RollbackResult>;

package/dist/core/validate.d.ts

@@ -0,0 +1,20 @@
+import type { ChunkRef, SegmentRef } from './ports.js';
+/**
+ * The most an encoded name may occupy in a physical key.
+ *
+ * S3's limit is 1024 bytes for the WHOLE key, which also carries the caller's prefix, the namespace, a fixed
+ * infix (`/segments/`) and the `.<generation>.crbm` suffix. 256 leaves generous room for all of that with both
+ * a namespace and a segment at the ceiling, and matches the limit the previous grammar advertised, so no name
+ * that was legal before becomes illegal now.
+ */
+export declare const MAX_NAME_LENGTH = 256;
+/**
+ * How long a name is once storage has it — the longer of the two encodings.
+ *
+ * Exported because anything that composes a name out of other names (the due index does) has to measure it the
+ * same way, and a second copy of that rule is how the two drifted apart before.
+ */
+export declare function encodedNameLength(value: string): number;
+export declare function validateSegmentRef(ref: SegmentRef): void;
+/** Validate a chunk ref: the segment/namespace rules plus `chunkKey` ∈ `[0, 65535]` (a u16). */
+export declare function validateChunkRef(ref: ChunkRef): void;

package/dist/driver-kit.d.ts

@@ -0,0 +1,10 @@
+export type { GenKey, IRegistryDriver, IStorageDriver, SegmentRef, StorageBackend, StorageCaps, } from './core/ports.js';
+export { brandAsBackend, STORAGE_BACKEND } from './core/ports.js';
+export { IntegrityError, isNotFoundError, isValidationError, isWriteConflictError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
+export { validateSegmentRef } from './core/validate.js';
+export type { BlobSink } from './core/blob.js';
+export { MAX_ROW_BYTES, ObjectStoreRegistry, ObjectVersionRaced, } from './drivers/_shared/object-registry.js';
+export type { ObjectRegistryStore, ObjectRow } from './drivers/_shared/object-registry.js';
+export { encodeNameForKey, namespaceKeyPart } from './drivers/_shared/keys.js';
+export { normalizeObjectPrefix, parseRegistryKey, prefixPart, registryListPrefix, registryObjectKey, registryPrefix, } from './drivers/_shared/object-registry-keys.js';
+export { errorName, httpStatus, isNetworkOrTimeout, isSdkRetryable, isServerSide, } from './drivers/_shared/aws-errors.js';

package/dist/driver-kit.js

@@ -0,0 +1,314 @@
+import {
+  DEFAULT_NAMESPACE,
+  IntegrityError,
+  NotFoundError,
+  STORAGE_BACKEND,
+  TransientError,
+  ValidationError,
+  WriteConflictError,
+  applyRegistryPatch,
+  brandAsBackend,
+  decodeNameFromKey,
+  encodeNameForKey,
+  isNotFoundError,
+  isValidationError,
+  isWriteConflictError,
+  mapWithConcurrency,
+  namespaceKeyPart,
+  parseRegistryEnvelope,
+  recordFromNew,
+  registryCounterOf,
+  serializeRegistryEnvelope,
+  validateNewRegistryRecord,
+  validateRegistryPatch,
+  validateSegmentRef
+} from "./chunk-BUPDGZRR.js";
+
+// src/drivers/_shared/object-registry-keys.ts
+var REGISTRY_SUFFIX = ".reg";
+function prefixPart(prefix) {
+  if (prefix === void 0) return "";
+  const trimmed = prefix.replace(/^\/+|\/+$/g, "");
+  return trimmed === "" ? "" : `${trimmed}/`;
+}
+function normalizeObjectPrefix(prefix) {
+  if (prefix === void 0) return void 0;
+  for (const ch of prefix) {
+    const code = ch.charCodeAt(0);
+    if (code < 32 || code === 127) {
+      throw new ValidationError("prefix must not contain control characters");
+    }
+  }
+  if (prefix.includes("\\")) {
+    throw new ValidationError(
+      `prefix must not contain backslashes (a path separator on some backends): ${JSON.stringify(prefix)}`
+    );
+  }
+  let decoded;
+  try {
+    decoded = decodeURIComponent(prefix);
+  } catch {
+    decoded = prefix;
+  }
+  for (const source of decoded === prefix ? [prefix] : [prefix, decoded]) {
+    for (const segment of source.split("/")) {
+      if (segment === "." || segment === "..") {
+        throw new ValidationError(
+          `prefix must not contain "." or ".." path segments: ${JSON.stringify(prefix)}`
+        );
+      }
+    }
+  }
+  return prefix;
+}
+function registryPrefix(prefix) {
+  return `${prefixPart(prefix)}registry/`;
+}
+function registryObjectKey(prefix, ref) {
+  validateSegmentRef(ref);
+  return `${registryPrefix(prefix)}${namespaceKeyPart(ref.namespace)}/${encodeNameForKey(ref.segment)}${REGISTRY_SUFFIX}`;
+}
+function registryListPrefix(prefix, namespace) {
+  const base = registryPrefix(prefix);
+  return namespace === void 0 ? base : `${base}${namespaceKeyPart(namespace)}/`;
+}
+function parseRegistryKey(prefix, objectKey) {
+  const base = registryPrefix(prefix);
+  if (!objectKey.startsWith(base) || !objectKey.endsWith(REGISTRY_SUFFIX)) return null;
+  const rest = objectKey.slice(base.length, objectKey.length - REGISTRY_SUFFIX.length);
+  const slash = rest.indexOf("/");
+  if (slash < 0) return null;
+  const nsPart = rest.slice(0, slash);
+  const encodedSegment = rest.slice(slash + 1);
+  if (encodedSegment.length === 0 || encodedSegment.includes("/")) return null;
+  const segment = decodeNameFromKey(encodedSegment);
+  const namespace = nsPart === DEFAULT_NAMESPACE ? void 0 : decodeNameFromKey(nsPart);
+  if (encodeNameForKey(segment) !== encodedSegment) return null;
+  if (namespace !== void 0 && encodeNameForKey(namespace) !== nsPart) return null;
+  const ref = { segment, namespace };
+  try {
+    validateSegmentRef(ref);
+  } catch {
+    return null;
+  }
+  return ref;
+}
+
+// src/drivers/_shared/object-registry.ts
+var MAX_ROW_BYTES = 1 * 1024 * 1024;
+var MAX_DELETE_ATTEMPTS = 8;
+var MAX_READ_ATTEMPTS = 8;
+var LIST_READ_CONCURRENCY = 16;
+var ObjectVersionRaced = class extends Error {
+  constructor(objectKey) {
+    super(`registry object was overwritten mid-read: ${objectKey}`);
+    this.name = "ObjectVersionRaced";
+  }
+};
+var ObjectStoreRegistry = class {
+  constructor(store, prefix, now) {
+    this.store = store;
+    this.prefix = prefix;
+    this.now = now;
+  }
+  store;
+  prefix;
+  now;
+  capabilities() {
+    return { strongRead: true };
+  }
+  async get(ref) {
+    const current = await this.readRow(registryObjectKey(this.prefix, ref));
+    return current && !current.env.deleted ? current.env.record : null;
+  }
+  async create(ref, record) {
+    validateNewRegistryRecord(record);
+    const key = registryObjectKey(this.prefix, ref);
+    const current = await this.readRow(key);
+    if (current !== null && !current.env.deleted) {
+      throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
+    }
+    const token = String(current ? registryCounterOf(current.env.record) + 1 : 0);
+    const env = {
+      deleted: false,
+      record: recordFromNew(ref, record, this.now(), token)
+    };
+    await this.putRow(key, env, current ? { version: current.version } : "absent");
+    return { token };
+  }
+  async compareAndSwap(ref, expected, patch) {
+    validateRegistryPatch(patch);
+    const key = registryObjectKey(this.prefix, ref);
+    const current = await this.readRow(key);
+    if (current === null || current.env.deleted || current.env.record.token !== expected) {
+      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+    }
+    const token = String(registryCounterOf(current.env.record) + 1);
+    const env = {
+      deleted: false,
+      record: applyRegistryPatch(current.env.record, patch, this.now(), token)
+    };
+    await this.putRow(key, env, { version: current.version });
+    return { token };
+  }
+  async *list(namespace) {
+    const prefix = registryListPrefix(this.prefix, namespace);
+    let page = [];
+    const flush = async function* (keys) {
+      const rows = await mapWithConcurrency(
+        keys,
+        LIST_READ_CONCURRENCY,
+        (key) => this.readRow(key)
+      );
+      for (const current of rows) {
+        if (current && !current.env.deleted) yield current.env.record;
+      }
+    }.bind(this);
+    for await (const key of this.store.listKeys(prefix)) {
+      if (parseRegistryKey(this.prefix, key) === null) continue;
+      page.push(key);
+      if (page.length >= LIST_READ_CONCURRENCY) {
+        yield* flush(page);
+        page = [];
+      }
+    }
+    if (page.length > 0) yield* flush(page);
+  }
+  async delete(ref) {
+    const key = registryObjectKey(this.prefix, ref);
+    for (let attempt = 0; attempt < MAX_DELETE_ATTEMPTS; attempt++) {
+      const current = await this.readRow(key);
+      if (current === null || current.env.deleted) return;
+      const token = String(registryCounterOf(current.env.record) + 1);
+      const env = {
+        deleted: true,
+        record: { ...current.env.record, token, updatedAt: this.now() }
+      };
+      try {
+        await this.putRow(key, env, { version: current.version });
+        return;
+      } catch (err) {
+        if (isWriteConflictError(err)) continue;
+        throw err;
+      }
+    }
+    throw new WriteConflictError(
+      `registry delete: contention tombstoning "${ref.segment}" \u2014 retry`
+    );
+  }
+  /**
+   * Read + parse a registry object, returning its envelope and version fence, or null if absent.
+   *
+   * A store that pins a version to read consistently ({@link ObjectVersionRaced}) loses that pin whenever a
+   * concurrent writer lands mid-read. Re-reading is the whole answer — the next read simply observes the
+   * newer version — and it is bounded so a row under permanent write saturation fails typed instead of
+   * spinning. Only a store racing itself gets here; S3 never does.
+   */
+  async readRow(objectKey) {
+    const row = await this.readRaced(objectKey);
+    if (row === null) return null;
+    if (row.bytes.length > MAX_ROW_BYTES) {
+      throw new IntegrityError(
+        `registry object ${row.bytes.length}B exceeds cap ${MAX_ROW_BYTES}B`
+      );
+    }
+    if (row.version.length === 0) {
+      throw new IntegrityError(
+        `registry object has no version fence (needed for compare-and-swap): ${objectKey}`
+      );
+    }
+    const env = parseRegistryEnvelope(new TextDecoder().decode(row.bytes), objectKey);
+    return { env, version: row.version };
+  }
+  /** {@link ObjectRegistryStore.read}, retrying the bounded number of times a mid-read overwrite allows. */
+  async readRaced(objectKey) {
+    for (let attempt = 0; attempt < MAX_READ_ATTEMPTS; attempt++) {
+      try {
+        return await this.store.read(objectKey);
+      } catch (err) {
+        if (!(err instanceof ObjectVersionRaced)) throw err;
+      }
+    }
+    throw new TransientError(
+      `registry read: ${this.store.label} object "${objectKey}" was overwritten on every one of ${MAX_READ_ATTEMPTS} attempts \u2014 retry`
+    );
+  }
+  /** Conditional write of an envelope. The store maps a lost precondition to {@link WriteConflictError}. */
+  async putRow(objectKey, env, expect) {
+    const body = new TextEncoder().encode(serializeRegistryEnvelope(env));
+    if (body.length > MAX_ROW_BYTES) {
+      throw new ValidationError(`registry object ${body.length}B exceeds cap ${MAX_ROW_BYTES}B`);
+    }
+    await this.store.write(objectKey, body, expect);
+  }
+};
+
+// src/drivers/_shared/aws-errors.ts
+function httpStatus(err) {
+  return err?.$metadata?.httpStatusCode;
+}
+function errorName(err) {
+  return err?.name;
+}
+function errorCode(err) {
+  return err?.code;
+}
+function isSdkRetryable(err) {
+  return err?.$retryable != null;
+}
+function isServerSide(err) {
+  const status = httpStatus(err);
+  return status !== void 0 && status >= 500 && status <= 599;
+}
+var NETWORK_NAMES = /* @__PURE__ */ new Set([
+  "TimeoutError",
+  "RequestTimeout",
+  "RequestTimeoutException",
+  "NetworkingError",
+  "AbortError"
+]);
+var NETWORK_CODES = /* @__PURE__ */ new Set([
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "EPIPE",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNABORTED"
+]);
+var NETWORK_MESSAGE = /socket hang up|network (error|failure)|(connection|request|socket|operation|read|write)\s+tim(e|ed)\s?out|connection (reset|refused|aborted|closed)/i;
+function isNetworkOrTimeout(err) {
+  if (NETWORK_NAMES.has(errorName(err) ?? "")) return true;
+  if (NETWORK_CODES.has(errorCode(err) ?? "")) return true;
+  return NETWORK_MESSAGE.test(err?.message ?? "");
+}
+export {
+  IntegrityError,
+  MAX_ROW_BYTES,
+  NotFoundError,
+  ObjectStoreRegistry,
+  ObjectVersionRaced,
+  STORAGE_BACKEND,
+  TransientError,
+  ValidationError,
+  WriteConflictError,
+  brandAsBackend,
+  encodeNameForKey,
+  errorName,
+  httpStatus,
+  isNetworkOrTimeout,
+  isNotFoundError,
+  isSdkRetryable,
+  isServerSide,
+  isValidationError,
+  isWriteConflictError,
+  namespaceKeyPart,
+  normalizeObjectPrefix,
+  parseRegistryKey,
+  prefixPart,
+  registryListPrefix,
+  registryObjectKey,
+  registryPrefix,
+  validateSegmentRef
+};
+//# sourceMappingURL=driver-kit.js.map

package/dist/driver-kit.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/drivers/_shared/object-registry-keys.ts", "../src/drivers/_shared/object-registry.ts", "../src/drivers/_shared/aws-errors.ts"],
+  "sourcesContent": ["/**\n * The registry object layout, shared by every object-store registry (S3, GCS, Azure Blob).\n *\n * One tiny JSON object per segment at `<prefix>registry/<ns>/<segment>.reg`, **registry-first** \u2014 separate\n * from the namespace-first storage layout (`<prefix><ns>/segments/\u2026`) \u2014 so discovery is a single list over\n * `registry/` for all namespaces, or `registry/<ns>/` for one, never entangled with the `.crbm` payloads.\n *\n * It lives here rather than in a driver because all three object stores encode names the same way\n * (`encodeNameForKey`, `namespaceKeyPart`) and build byte-identical keys. Three copies of this would be\n * three chances for one cloud's layout to drift from the others \u2014 and a drifted key is not a visible bug, it\n * is a segment that quietly cannot be found by a store pointed at the same bucket.\n */\nimport { ValidationError } from '@/core/errors';\nimport { validateSegmentRef } from '@/core/validate';\nimport type { SegmentRef } from '@/core/ports';\nimport { DEFAULT_NAMESPACE, decodeNameFromKey, encodeNameForKey, namespaceKeyPart } from './keys';\n\nconst REGISTRY_SUFFIX = '.reg';\n\n/** Normalize an optional caller prefix to either `''` or `trimmed/` (no leading/trailing slashes). */\nexport function prefixPart(prefix: string | undefined): string {\n  if (prefix === undefined) return '';\n  const trimmed = prefix.replace(/^\\/+|\\/+$/g, '');\n  return trimmed === '' ? '' : `${trimmed}/`;\n}\n\n/**\n * Validate a caller-supplied key prefix (trusted config, but make it a real containment boundary): reject\n * control characters and `.`/`..` path segments so a prefix cannot traverse out of its intended space.\n * Returns it unchanged \u2014 the key builders normalize slashes.\n *\n * The traversal check covers three spellings, because the tools that walk these buckets do. A bare `..` is\n * the obvious one. A **backslash** segment matters on ADLS Gen2 and to Windows-side tooling, which treat it\n * as a separator this code otherwise would not. And a percent-encoded `..` matters because `gsutil`,\n * `s3fs`, `gcsfuse` and `azcopy` decode a key on their way to a local path \u2014 the same reasoning\n * `name-codec.ts` already applies to segment names, which a prefix has no reason to be exempt from.\n */\nexport function normalizeObjectPrefix(prefix: string | undefined): string | undefined {\n  if (prefix === undefined) return undefined;\n  for (const ch of prefix) {\n    const code = ch.charCodeAt(0);\n    // C0 plus DEL: a bare `< 0x20` lets U+007F through, and it is as unprintable as the rest.\n    if (code < 0x20 || code === 0x7f) {\n      throw new ValidationError('prefix must not contain control characters');\n    }\n  }\n  if (prefix.includes('\\\\')) {\n    throw new ValidationError(\n      `prefix must not contain backslashes (a path separator on some backends): ${JSON.stringify(prefix)}`,\n    );\n  }\n  // Check the decoded spelling too, so an encoded `..` cannot slip past the literal comparison.\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(prefix);\n  } catch {\n    decoded = prefix; // not valid percent-encoding; the literal check still applies\n  }\n  for (const source of decoded === prefix ? [prefix] : [prefix, decoded]) {\n    for (const segment of source.split('/')) {\n      if (segment === '.' || segment === '..') {\n        throw new ValidationError(\n          `prefix must not contain \".\" or \"..\" path segments: ${JSON.stringify(prefix)}`,\n        );\n      }\n    }\n  }\n  return prefix;\n}\n\n/** The key prefix under which every registry object lives: `<prefix>registry/`. */\nexport function registryPrefix(prefix: string | undefined): string {\n  return `${prefixPart(prefix)}registry/`;\n}\n\n/** The full key of one segment's registry object: `<prefix>registry/<ns>/<segment>.reg`. */\nexport function registryObjectKey(prefix: string | undefined, ref: SegmentRef): string {\n  validateSegmentRef(ref);\n  return `${registryPrefix(prefix)}${namespaceKeyPart(ref.namespace)}/${encodeNameForKey(ref.segment)}${REGISTRY_SUFFIX}`;\n}\n\n/** The list prefix for discovery: registry-wide, or scoped to one namespace. */\nexport function registryListPrefix(prefix: string | undefined, namespace?: string): string {\n  const base = registryPrefix(prefix);\n  return namespace === undefined ? base : `${base}${namespaceKeyPart(namespace)}/`;\n}\n\n/**\n * Parse a `<prefix>registry/<ns>/<segment>.reg` key back to its {@link SegmentRef}, or `null` if it does not\n * match \u2014 a stray or foreign object under the prefix, or one whose parsed ref fails the round-trip check.\n * `_default` maps back to the absent namespace. A name is percent-encoded on the way in, so no encoded name\n * can contain `/` and the split stays unambiguous whatever the caller named their segment.\n */\nexport function parseRegistryKey(prefix: string | undefined, objectKey: string): SegmentRef | null {\n  const base = registryPrefix(prefix);\n  if (!objectKey.startsWith(base) || !objectKey.endsWith(REGISTRY_SUFFIX)) return null;\n  const rest = objectKey.slice(base.length, objectKey.length - REGISTRY_SUFFIX.length);\n  const slash = rest.indexOf('/');\n  if (slash < 0) return null;\n  const nsPart = rest.slice(0, slash);\n  const encodedSegment = rest.slice(slash + 1);\n  if (encodedSegment.length === 0 || encodedSegment.includes('/')) return null;\n  const segment = decodeNameFromKey(encodedSegment);\n  const namespace = nsPart === DEFAULT_NAMESPACE ? undefined : decodeNameFromKey(nsPart);\n  // The encoding must ROUND-TRIP, not merely decode: a foreign object placed under our prefix could spell a\n  // name two ways, and reporting both would hand a sweep one segment under two identities.\n  if (encodeNameForKey(segment) !== encodedSegment) return null;\n  if (namespace !== undefined && encodeNameForKey(namespace) !== nsPart) return null;\n  const ref: SegmentRef = { segment, namespace };\n  try {\n    validateSegmentRef(ref); // reject a hostile/foreign key that isn't a valid ref\n  } catch {\n    return null;\n  }\n  return ref;\n}\n", "/**\n * `ObjectStoreRegistry` \u2014 an {@link IRegistryDriver} over any object store with conditional writes.\n *\n * Lets a **read-mostly deployment run on one bucket alone** \u2014 storage `.crbm` generations plus the registry in\n * the same place, with no separate database. One tiny JSON object per segment at\n * `<prefix>registry/<ns>/<segment>.reg` holding the `{ deleted, record }` envelope (the same shape LocalFs\n * persists). The OCC token is a monotonic counter, advanced on every mutation and even across a `delete`\n * (which **tombstones** rather than removes the object) so a deleted-then-recreated row never re-issues an\n * old token (ABA-safe) \u2014 identical semantics to the LocalFs registry, so it passes the same conformance suite.\n *\n * **The atomic swap is offloaded to the store's conditional writes.** `create` writes only if absent (or\n * over a tombstone under its version), and `compareAndSwap`/`delete` write only if the object still carries\n * the version we read \u2014 so a concurrent writer between our read and our write loses, and the loss surfaces\n * as {@link WriteConflictError}. No in-process lock is needed (unlike LocalFs): the precondition fences\n * writers *across processes*.\n *\n * **Why this is shared rather than written per cloud.** Every object store worth using has the same two\n * primitives under different names \u2014 S3 `If-None-Match: *` / `If-Match: <etag>`, GCS `ifGenerationMatch: 0`\n * / `ifGenerationMatch: <generation>`, Azure `If-None-Match: *` / `If-Match: <etag>` \u2014 so the only thing\n * that differs is three I/O calls, which is what {@link ObjectRegistryStore} abstracts. The parts that are\n * genuinely hard (the ABA-safe counter, the tombstone, the bounded delete retry, the round-trip key check)\n * exist once. Three copies would be three chances for one cloud to drift, and a drifted registry is not a\n * visible bug \u2014 it is a lost `currentGen` swap.\n *\n * **Deployment requirements** (a backend that violates these silently corrupts the registry):\n * - The store **must honor the conditional write**. One that accepts the precondition header and ignores it\n *   degrades compare-and-swap to last-write-wins \u2192 lost `currentGen` swaps.\n * - Reads must be **strongly consistent** \u2014 true of S3 (since 2020), GCS and Azure Blob \u2014 since the registry\n *   advertises `strongRead` and generation resolution depends on it.\n * - **Do not apply a lifecycle-expiration rule to the `registry/` prefix.** `delete` tombstones (keeps the\n *   object with an advanced counter) for ABA-safety; expiring a tombstone would let a recreate reset the\n *   token to 0 and re-issue a stale one.\n *\n * **`list()` is fail-closed, and one bad object stops it for everyone.** An object under the `registry/`\n * prefix whose key parses but whose body does not aborts the whole enumeration \u2014 every namespace, not just\n * the affected segment \u2014 and it stays that way until an operator removes the object. The error names the\n * offending key.\n *\n * That is the deliberate choice, and it is the *safer* one rather than the more convenient one. Skipping the\n * unreadable row would keep discovery running, but `list()` is what tells orphan generation collection which\n * segments exist: a row missing from the enumeration makes its storage `.crbm` generations look unreferenced,\n * and the next GC pass would delete them. Silently skipping turns a parse error into data loss. Refusing to\n * enumerate keeps every sweep off a set it cannot vouch for (invariant 5 \u2014 bytes from the tier are\n * untrusted). **Recovery:** read the named object, and either restore a valid envelope or delete it; nothing\n * else is damaged, and discovery resumes on its own.\n */\nimport {\n  IntegrityError,\n  TransientError,\n  ValidationError,\n  WriteConflictError,\n  isWriteConflictError,\n} from '@/core/errors';\nimport type {\n  IRegistryDriver,\n  NewRegistryRecord,\n  RegCaps,\n  RegistryPatch,\n  RegistryRecord,\n  SegmentRef,\n  Token,\n} from '@/core/ports';\nimport { mapWithConcurrency } from '@/core/concurrency';\nimport {\n  applyRegistryPatch,\n  parseRegistryEnvelope,\n  recordFromNew,\n  registryCounterOf,\n  serializeRegistryEnvelope,\n  validateNewRegistryRecord,\n  validateRegistryPatch,\n  type RegistryEnvelope,\n} from './registry';\nimport { parseRegistryKey, registryListPrefix, registryObjectKey } from './object-registry-keys';\n\n/** Defensive cap on a single registry object read from storage, before allocation (rows are tiny; ~1 KB). */\nexport const MAX_ROW_BYTES = 1 * 1024 * 1024;\n/** Bounded retry for `delete`'s read\u2192tombstone under cross-process contention (converges; then fails typed). */\nconst MAX_DELETE_ATTEMPTS = 8;\n/** Bounded re-read when a store's pinned version is overwritten mid-read (see {@link ObjectVersionRaced}). */\nconst MAX_READ_ATTEMPTS = 8;\n/** In-flight reads per `list()` page \u2014 turns the serial N+1 into one list plus bounded parallel reads. */\nconst LIST_READ_CONCURRENCY = 16;\n\n/**\n * Raised by a store when the version it pinned for a read vanished before it could fetch the bytes \u2014\n * a concurrent writer overwrote or deleted the object in between.\n *\n * This is deliberately **neither** of the two things it superficially resembles. It is not absence: the row\n * is very likely still live, just one version further on. And it is not a write conflict: the caller may be\n * a read-only `get()`, which has nothing to conflict with. Both of those mistakes were made \u2014 one per cloud \u2014\n * before this type existed, which is exactly why the signal is now part of the port rather than left to each\n * store's judgement. {@link ObjectStoreRegistry} answers it the only way that is correct for every caller:\n * it reads again.\n *\n * Stores whose read is atomic (S3 serves bytes and `ETag` from one `GetObject`) can never raise it.\n */\nexport class ObjectVersionRaced extends Error {\n  constructor(objectKey: string) {\n    super(`registry object was overwritten mid-read: ${objectKey}`);\n    this.name = 'ObjectVersionRaced';\n  }\n}\n\n/** One object as read, with the opaque version that fences a later conditional write. */\nexport interface ObjectRow {\n  readonly bytes: Uint8Array;\n  /** The store's version fence \u2014 an S3/Azure ETag, a GCS generation. Opaque to this class. */\n  readonly version: string;\n}\n\n/**\n * The three I/O calls an object store must provide to host a registry. Everything else \u2014 the OCC counter,\n * tombstones, the delete retry, key parsing \u2014 is implemented once above.\n */\nexport interface ObjectRegistryStore {\n  /** A label for error messages, e.g. `GCS` or `Azure Blob`. */\n  readonly label: string;\n  /**\n   * Read one object, or `null` when it is absent.\n   *\n   * **`null` means the object does not exist** \u2014 nothing weaker. A store that reads in two round trips\n   * (metadata for the version fence, then the bytes pinned to it) can find that version already gone; it\n   * MUST report that with {@link ObjectVersionRaced} rather than `null` or {@link WriteConflictError}, and\n   * the caller re-reads. Retryable faults throw {@link TransientError}.\n   *\n   * `bytes` and `version` MUST describe the **same** observation of the object: `version` is the fence a\n   * later conditional write is conditioned on, so a pair drawn from two different versions would either\n   * fail a write that should have succeeded or, worse, pass one that should not.\n   */\n  read(key: string): Promise<ObjectRow | null>;\n  /**\n   * Write one object under a precondition: `'absent'` means create-only, a version means\n   * compare-and-swap against exactly that version. A lost race MUST throw {@link WriteConflictError}.\n   */\n  write(key: string, body: Uint8Array, expect: 'absent' | { version: string }): Promise<void>;\n  /** Every object key under `prefix`, paginated internally. */\n  listKeys(prefix: string): AsyncIterable<string>;\n}\n\nexport class ObjectStoreRegistry implements IRegistryDriver {\n  constructor(\n    private readonly store: ObjectRegistryStore,\n    private readonly prefix: string | undefined,\n    private readonly now: () => number,\n  ) {}\n\n  capabilities(): RegCaps {\n    return { strongRead: true };\n  }\n\n  async get(ref: SegmentRef): Promise<RegistryRecord | null> {\n    const current = await this.readRow(registryObjectKey(this.prefix, ref));\n    return current && !current.env.deleted ? current.env.record : null;\n  }\n\n  async create(ref: SegmentRef, record: NewRegistryRecord): Promise<{ token: Token }> {\n    validateNewRegistryRecord(record);\n    const key = registryObjectKey(this.prefix, ref);\n    const current = await this.readRow(key);\n    if (current !== null && !current.env.deleted) {\n      throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);\n    }\n    // Advance across a tombstone so a recreate never re-issues an old token (ABA-safe).\n    const token = String(current ? registryCounterOf(current.env.record) + 1 : 0);\n    const env: RegistryEnvelope = {\n      deleted: false,\n      record: recordFromNew(ref, record, this.now(), token),\n    };\n    // Create-only when truly absent; overwrite the tombstone under its version when recreating. Either way\n    // a concurrent create loses the precondition and surfaces as a conflict.\n    await this.putRow(key, env, current ? { version: current.version } : 'absent');\n    return { token };\n  }\n\n  async compareAndSwap(\n    ref: SegmentRef,\n    expected: Token,\n    patch: RegistryPatch,\n  ): Promise<{ token: Token }> {\n    validateRegistryPatch(patch);\n    const key = registryObjectKey(this.prefix, ref);\n    const current = await this.readRow(key);\n    if (current === null || current.env.deleted || current.env.record.token !== expected) {\n      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);\n    }\n    const token = String(registryCounterOf(current.env.record) + 1);\n    const env: RegistryEnvelope = {\n      deleted: false,\n      record: applyRegistryPatch(current.env.record, patch, this.now(), token),\n    };\n    // The version we read fences a concurrent writer between that read and this write.\n    await this.putRow(key, env, { version: current.version });\n    return { token };\n  }\n\n  async *list(namespace?: string): AsyncIterable<RegistryRecord> {\n    const prefix = registryListPrefix(this.prefix, namespace);\n    // One list plus bounded parallel reads. A serial await-in-loop made this O(N) sequential round trips.\n    let page: string[] = [];\n    const flush = async function* (\n      this: ObjectStoreRegistry,\n      keys: string[],\n    ): AsyncIterable<RegistryRecord> {\n      const rows = await mapWithConcurrency(keys, LIST_READ_CONCURRENCY, (key) =>\n        this.readRow(key),\n      );\n      for (const current of rows) {\n        if (current && !current.env.deleted) yield current.env.record;\n      }\n    }.bind(this);\n\n    for await (const key of this.store.listKeys(prefix)) {\n      if (parseRegistryKey(this.prefix, key) === null) continue; // stray or foreign object\n      page.push(key);\n      if (page.length >= LIST_READ_CONCURRENCY) {\n        yield* flush(page);\n        page = [];\n      }\n    }\n    if (page.length > 0) yield* flush(page);\n  }\n\n  async delete(ref: SegmentRef): Promise<void> {\n    const key = registryObjectKey(this.prefix, ref);\n    // Tombstone (advance the counter) rather than remove the object \u2014 keeps the token monotonic for\n    // ABA-safety. Retry the read\u2192tombstone on a cross-process race; it converges, then fails typed rather\n    // than silently leaving the row live.\n    for (let attempt = 0; attempt < MAX_DELETE_ATTEMPTS; attempt++) {\n      const current = await this.readRow(key);\n      if (current === null || current.env.deleted) return; // idempotent \u2014 already gone\n      const token = String(registryCounterOf(current.env.record) + 1);\n      const env: RegistryEnvelope = {\n        deleted: true,\n        record: { ...current.env.record, token, updatedAt: this.now() },\n      };\n      try {\n        await this.putRow(key, env, { version: current.version });\n        return;\n      } catch (err) {\n        if (isWriteConflictError(err)) continue; // raced \u2014 re-read and re-tombstone\n        throw err;\n      }\n    }\n    throw new WriteConflictError(\n      `registry delete: contention tombstoning \"${ref.segment}\" \u2014 retry`,\n    );\n  }\n\n  /**\n   * Read + parse a registry object, returning its envelope and version fence, or null if absent.\n   *\n   * A store that pins a version to read consistently ({@link ObjectVersionRaced}) loses that pin whenever a\n   * concurrent writer lands mid-read. Re-reading is the whole answer \u2014 the next read simply observes the\n   * newer version \u2014 and it is bounded so a row under permanent write saturation fails typed instead of\n   * spinning. Only a store racing itself gets here; S3 never does.\n   */\n  private async readRow(\n    objectKey: string,\n  ): Promise<{ env: RegistryEnvelope; version: string } | null> {\n    const row = await this.readRaced(objectKey);\n    if (row === null) return null;\n    if (row.bytes.length > MAX_ROW_BYTES) {\n      throw new IntegrityError(\n        `registry object ${row.bytes.length}B exceeds cap ${MAX_ROW_BYTES}B`,\n      );\n    }\n    if (row.version.length === 0) {\n      // The version is the OCC fence for CAS; a backend that omits it cannot be used safely as a registry.\n      throw new IntegrityError(\n        `registry object has no version fence (needed for compare-and-swap): ${objectKey}`,\n      );\n    }\n    const env = parseRegistryEnvelope(new TextDecoder().decode(row.bytes), objectKey);\n    return { env, version: row.version };\n  }\n\n  /** {@link ObjectRegistryStore.read}, retrying the bounded number of times a mid-read overwrite allows. */\n  private async readRaced(objectKey: string): Promise<ObjectRow | null> {\n    for (let attempt = 0; attempt < MAX_READ_ATTEMPTS; attempt++) {\n      try {\n        return await this.store.read(objectKey);\n      } catch (err) {\n        if (!(err instanceof ObjectVersionRaced)) throw err;\n      }\n    }\n    throw new TransientError(\n      `registry read: ${this.store.label} object \"${objectKey}\" was overwritten on every one of ` +\n        `${MAX_READ_ATTEMPTS} attempts \u2014 retry`,\n    );\n  }\n\n  /** Conditional write of an envelope. The store maps a lost precondition to {@link WriteConflictError}. */\n  private async putRow(\n    objectKey: string,\n    env: RegistryEnvelope,\n    expect: 'absent' | { version: string },\n  ): Promise<void> {\n    const body = new TextEncoder().encode(serializeRegistryEnvelope(env));\n    if (body.length > MAX_ROW_BYTES) {\n      // Belt-and-braces: the governance/DEK fields are already capped by validate*, so this cannot fire for\n      // valid input \u2014 but never write a row that would later be unreadable.\n      throw new ValidationError(`registry object ${body.length}B exceeds cap ${MAX_ROW_BYTES}B`);\n    }\n    await this.store.write(objectKey, body, expect);\n  }\n}\n", "/**\n * Shared, SDK-free helpers for classifying AWS-style errors (used by the S3 drivers).\n *\n * These only read structural shapes an AWS SDK v3 error carries \u2014 `name`, `$metadata.httpStatusCode`, a\n * lower-level `code`/`errno`, and the SDK's own `$retryable` marker \u2014 so the (subtle, easy-to-get-wrong)\n * transient-vs-fatal decision is unit-testable without a live backend or even the SDK installed. They live\n * under `drivers/_shared` (part of the SDK-free core bundle): a driver may import them; they import no SDK.\n */\n\nexport function httpStatus(err: unknown): number | undefined {\n  return (err as { $metadata?: { httpStatusCode?: number } } | null)?.$metadata?.httpStatusCode;\n}\n\nexport function errorName(err: unknown): string | undefined {\n  return (err as { name?: string } | null)?.name;\n}\n\n/** A lower-level transport code (e.g. `ECONNRESET`) \u2014 the Node networking layer sets `code`. */\nexport function errorCode(err: unknown): string | undefined {\n  return (err as { code?: string } | null)?.code;\n}\n\n/** The AWS SDK v3 tags retryable errors with a `$retryable` object (throttling faults carry `.throttling`). */\nexport function isSdkRetryable(err: unknown): boolean {\n  return (err as { $retryable?: unknown } | null)?.$retryable != null;\n}\n\n/** Any 5xx is a server-side fault that's safe to retry (the request didn't deterministically fail). */\nexport function isServerSide(err: unknown): boolean {\n  const status = httpStatus(err);\n  return status !== undefined && status >= 500 && status <= 599;\n}\n\nconst NETWORK_NAMES = new Set([\n  'TimeoutError',\n  'RequestTimeout',\n  'RequestTimeoutException',\n  'NetworkingError',\n  'AbortError',\n]);\nconst NETWORK_CODES = new Set([\n  'ETIMEDOUT',\n  'ECONNRESET',\n  'ECONNREFUSED',\n  'EPIPE',\n  'ENOTFOUND',\n  'EAI_AGAIN',\n  'ECONNABORTED',\n]);\n\n// Message-text fallback for when the structural signals (name/code/$metadata/$retryable) are absent. Kept\n// SPECIFIC on purpose: a loose `/timed? ?out/` matches deterministic messages like \"value timed out of\n// range\" and would wrongly retry them, so we only match timeout/network phrases anchored to a transport word\n// (connection/request/socket/read/write) plus the unambiguous standalone phrases.\nconst NETWORK_MESSAGE =\n  /socket hang up|network (error|failure)|(connection|request|socket|operation|read|write)\\s+tim(e|ed)\\s?out|connection (reset|refused|aborted|closed)/i;\n\n/** A dropped/timed-out connection \u2014 transient by nature; a retry on a fresh connection usually succeeds. */\nexport function isNetworkOrTimeout(err: unknown): boolean {\n  if (NETWORK_NAMES.has(errorName(err) ?? '')) return true;\n  if (NETWORK_CODES.has(errorCode(err) ?? '')) return true;\n  return NETWORK_MESSAGE.test((err as { message?: string } | null)?.message ?? '');\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/drivers/_shared/aws-errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared, SDK-free helpers for classifying AWS-style errors (used by the S3 drivers).
+ *
+ * These only read structural shapes an AWS SDK v3 error carries — `name`, `$metadata.httpStatusCode`, a
+ * lower-level `code`/`errno`, and the SDK's own `$retryable` marker — so the (subtle, easy-to-get-wrong)
+ * transient-vs-fatal decision is unit-testable without a live backend or even the SDK installed. They live
+ * under `drivers/_shared` (part of the SDK-free core bundle): a driver may import them; they import no SDK.
+ */
+export declare function httpStatus(err: unknown): number | undefined;
+export declare function errorName(err: unknown): string | undefined;
+/** A lower-level transport code (e.g. `ECONNRESET`) — the Node networking layer sets `code`. */
+export declare function errorCode(err: unknown): string | undefined;
+/** The AWS SDK v3 tags retryable errors with a `$retryable` object (throttling faults carry `.throttling`). */
+export declare function isSdkRetryable(err: unknown): boolean;
+/** Any 5xx is a server-side fault that's safe to retry (the request didn't deterministically fail). */
+export declare function isServerSide(err: unknown): boolean;
+/** A dropped/timed-out connection — transient by nature; a retry on a fresh connection usually succeeds. */
+export declare function isNetworkOrTimeout(err: unknown): boolean;

package/dist/drivers/_shared/keys.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared key-grammar fragments used by every driver's logical-ref → physical-key mapping.
+ *
+ * Extracted once the registry drivers became the third consumer of the same `_default` namespace sentinel
+ * (it lived copy-pasted in `s3/keys` and `localfs/paths`). Pure string logic, no SDK, no I/O —
+ * lives in the SDK-free `_shared` bundle so any driver may import it.
+ */
+/**
+ * The physical stand-in for an **absent** namespace. A caller MAY name a namespace `_default`; it simply does not collide, because
+ * `namespaceKeyPart`/`namespacePathPart` encode the caller's namespace (to `%5Fdefault`) and emit this
+ * sentinel literally. The separation is a property of the encoding, not of a grammar — an earlier version of
+ * this comment claimed the latter, and that claim is exactly what made the collision easy to reintroduce.
+ */
+export declare const DEFAULT_NAMESPACE = "_default";
+/**
+ * The physical namespace component of an **object key**: the caller's namespace encoded, or the sentinel.
+ *
+ * The sentinel is emitted **literally, never encoded**, and that asymmetry is the whole point. Encoding it too
+ * would send an absent namespace to `%5Fdefault` — exactly where a caller who names their namespace `_default`
+ * already goes, since the encoder escapes their leading underscore. Both would land in one place and read each
+ * other's data. Encoding only the caller's side means `_default` (ours) and `%5Fdefault` (theirs) are two
+ * different strings, and no caller can produce the first.
+ */
+export declare function namespaceKeyPart(namespace: string | undefined): string;
+/** As {@link namespaceKeyPart}, for a filesystem path component. */
+export declare function namespacePathPart(namespace: string | undefined): string;
+export { encodeNameForKey, decodeNameFromKey, encodeNameForPath, decodeNameFromPath, } from '../../core/name-codec.js';

package/dist/drivers/_shared/object-registry-keys.d.ts

@@ -0,0 +1,28 @@
+import type { SegmentRef } from '../../core/ports.js';
+/** Normalize an optional caller prefix to either `''` or `trimmed/` (no leading/trailing slashes). */
+export declare function prefixPart(prefix: string | undefined): string;
+/**
+ * Validate a caller-supplied key prefix (trusted config, but make it a real containment boundary): reject
+ * control characters and `.`/`..` path segments so a prefix cannot traverse out of its intended space.
+ * Returns it unchanged — the key builders normalize slashes.
+ *
+ * The traversal check covers three spellings, because the tools that walk these buckets do. A bare `..` is
+ * the obvious one. A **backslash** segment matters on ADLS Gen2 and to Windows-side tooling, which treat it
+ * as a separator this code otherwise would not. And a percent-encoded `..` matters because `gsutil`,
+ * `s3fs`, `gcsfuse` and `azcopy` decode a key on their way to a local path — the same reasoning
+ * `name-codec.ts` already applies to segment names, which a prefix has no reason to be exempt from.
+ */
+export declare function normalizeObjectPrefix(prefix: string | undefined): string | undefined;
+/** The key prefix under which every registry object lives: `<prefix>registry/`. */
+export declare function registryPrefix(prefix: string | undefined): string;
+/** The full key of one segment's registry object: `<prefix>registry/<ns>/<segment>.reg`. */
+export declare function registryObjectKey(prefix: string | undefined, ref: SegmentRef): string;
+/** The list prefix for discovery: registry-wide, or scoped to one namespace. */
+export declare function registryListPrefix(prefix: string | undefined, namespace?: string): string;
+/**
+ * Parse a `<prefix>registry/<ns>/<segment>.reg` key back to its {@link SegmentRef}, or `null` if it does not
+ * match — a stray or foreign object under the prefix, or one whose parsed ref fails the round-trip check.
+ * `_default` maps back to the absent namespace. A name is percent-encoded on the way in, so no encoded name
+ * can contain `/` and the split stays unambiguous whatever the caller named their segment.
+ */
+export declare function parseRegistryKey(prefix: string | undefined, objectKey: string): SegmentRef | null;