@cloudbitmaps/core 0.22.0 → 0.23.0

package/dist/node.js

@@ -0,0 +1,1064 @@
+import {
+  BufferSink,
+  checkTailLength,
+  segmentKey
+} from "./chunk-GKHERVVQ.js";
+import {
+  DEFAULT_NAMESPACE,
+  applyRegistryPatch,
+  checkDeleteOptions,
+  checkNow,
+  checkRegistryWriteOptions,
+  drawIncarnation,
+  drawWrite,
+  entropyIsAvailable,
+  namespacePathPart,
+  newIncarnationToken,
+  nextRegistryToken,
+  parseRegistryEnvelope,
+  recordFromNew,
+  serializeRegistryEnvelope,
+  validateNewRegistryRecord,
+  validateRegistryPatch,
+  webCryptoEntropy
+} from "./chunk-7GT632UF.js";
+import {
+  IntegrityError,
+  KeyUnavailableError,
+  NotFoundError,
+  TransientError,
+  ValidationError,
+  WriteConflictError,
+  brandAsBackend,
+  decodeNameFromPath,
+  encodeNameForPath,
+  incarnationOf,
+  refuseUnknownOptions,
+  requireInteger,
+  validateSegmentRef
+} from "./chunk-MVUD4R72.js";
+
+// src/drivers/backends.ts
+import { join as join5 } from "node:path";
+
+// src/drivers/memory.ts
+import { createHash } from "node:crypto";
+var MemoryRegistryDriver = class {
+  rows = /* @__PURE__ */ new Map();
+  now;
+  entropy;
+  seq = 0;
+  constructor(options = {}) {
+    this.now = options.now ?? (() => Date.now());
+    this.entropy = options.entropy ?? webCryptoEntropy;
+  }
+  nextToken(incarnation) {
+    this.seq += 1;
+    return `${incarnation}.${this.seq}.${drawWrite(this.entropy)}`;
+  }
+  /** `conditionalDelete`: a delete checks the token and removes the row in one step, with no await between. */
+  capabilities() {
+    return entropyIsAvailable(this.entropy) ? { strongRead: true, conditionalDelete: true } : { strongRead: true, canWrite: false, conditionalDelete: true };
+  }
+  /** Every write reports its token to `onToken` before it is applied. */
+  get reportsWriteTokens() {
+    return true;
+  }
+  async get(ref) {
+    validateSegmentRef(ref);
+    const row = this.rows.get(segmentKey(ref));
+    return row ? structuredClone(row) : null;
+  }
+  async create(ref, record, options) {
+    checkRegistryWriteOptions(options);
+    validateSegmentRef(ref);
+    const checked = validateNewRegistryRecord(record);
+    const key = segmentKey(ref);
+    if (this.rows.has(key)) {
+      throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
+    }
+    const token = this.nextToken(drawIncarnation(this.entropy));
+    options?.onToken?.(token);
+    this.rows.set(key, structuredClone(recordFromNew(ref, checked, this.now(), token)));
+    return { token };
+  }
+  /**
+   * A caller's `held` row (see `RegistryWriteOptions`) has no read to spare here: the token is compared with the stored row in the same step
+   * as the write, in memory, so a stale one fails exactly as a lost race does.
+   */
+  async compareAndSwap(ref, expected, patch, options) {
+    checkRegistryWriteOptions(options);
+    validateSegmentRef(ref);
+    const checked = validateRegistryPatch(patch);
+    const key = segmentKey(ref);
+    const existing = this.rows.get(key);
+    if (!existing || existing.token !== expected) {
+      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+    }
+    const token = this.nextToken(incarnationOf(existing.token));
+    options?.onToken?.(token);
+    this.rows.set(key, structuredClone(applyRegistryPatch(existing, checked, this.now(), token)));
+    return { token };
+  }
+  async *list(namespace) {
+    if (namespace !== void 0) validateSegmentRef({ segment: "x", namespace });
+    for (const row of [...this.rows.values()]) {
+      if (namespace === void 0 || row.namespace === namespace) yield structuredClone(row);
+    }
+  }
+  async delete(ref, expected) {
+    validateSegmentRef(ref);
+    const key = segmentKey(ref);
+    if (expected !== void 0 && this.rows.get(key)?.token !== expected) {
+      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+    }
+    this.rows.delete(key);
+  }
+};
+var MemoryStorageDriver = class {
+  objects = /* @__PURE__ */ new Map();
+  stored = 0;
+  capabilities() {
+    return {
+      rangeRead: true,
+      maxObjectBytes: Number.MAX_SAFE_INTEGER,
+      conditionalPut: true,
+      conditionalDelete: true
+    };
+  }
+  async putImmutable(key, write) {
+    const k = genObjectKey(key);
+    const sink = new BufferSink();
+    await write(sink);
+    const body = sink.bytes();
+    if (this.objects.has(k)) {
+      throw new WriteConflictError(
+        `generation already exists (write-once): ${key.segment}.${key.generation}`
+      );
+    }
+    this.stored += 1;
+    this.objects.set(k, { body, version: String(this.stored) });
+    return { size: body.length, sha256: createHash("sha256").update(body).digest("hex") };
+  }
+  async getRange(key, offset, length) {
+    requireInteger(offset, { min: 0, what: "range offset" });
+    requireInteger(length, { min: 0, what: "range length" });
+    const { body } = this.require(key);
+    if (offset + length > body.length) {
+      throw new ValidationError(
+        `range [${offset}, ${offset + length}) out of bounds for ${body.length}B`
+      );
+    }
+    return body.slice(offset, offset + length);
+  }
+  async getTail(key, maxBytes) {
+    checkTailLength(maxBytes);
+    const { body, version } = this.require(key);
+    const take = Math.min(Math.max(maxBytes, 0), body.length);
+    return { bytes: body.slice(body.length - take), size: body.length, version };
+  }
+  async delete(key, options) {
+    const ifVersion = checkDeleteOptions(options);
+    const k = genObjectKey(key);
+    const stored = this.objects.get(k);
+    if (ifVersion !== void 0 && stored !== void 0 && stored.version !== ifVersion) {
+      throw new WriteConflictError(
+        `generation ${key.segment}.${key.generation} is another object than the version given; not deleted`
+      );
+    }
+    this.objects.delete(k);
+  }
+  async *list(ref) {
+    validateSegmentRef(ref);
+    const prefix = `${segmentKey(ref)} `;
+    for (const k of [...this.objects.keys()]) {
+      if (k.startsWith(prefix)) {
+        yield {
+          namespace: ref.namespace,
+          segment: ref.segment,
+          generation: Number(k.slice(prefix.length))
+        };
+      }
+    }
+  }
+  require(key) {
+    const stored = this.objects.get(genObjectKey(key));
+    if (stored === void 0) {
+      throw new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
+    }
+    return stored;
+  }
+};
+function genObjectKey(key) {
+  validateSegmentRef(key);
+  requireInteger(key.generation, { min: 0, what: "generation" });
+  return `${segmentKey(key)} ${key.generation}`;
+}
+
+// src/drivers/localfs/storage.ts
+import { constants as FS2 } from "node:fs";
+import { createHash as createHash2 } from "node:crypto";
+import { link, open as open2, readdir as readdir2, unlink as unlink2 } from "node:fs/promises";
+import { dirname as dirname3 } from "node:path";
+
+// src/drivers/localfs/paths.ts
+import { join } from "node:path";
+var MAX_COMPONENT_BYTES = 255;
+var TEMP_SUFFIX_BYTES = 1 + 36 + 4;
+function assertFits(component, extraBytes) {
+  if (component.length + extraBytes > MAX_COMPONENT_BYTES) {
+    throw new ValidationError(
+      `a name is too long for a file name on this backend: the namespace, or the segment with its generation and the temp file's suffix, must fit in ${MAX_COMPONENT_BYTES} bytes once encoded`
+    );
+  }
+}
+function assertStorageNamesFit(key) {
+  validateSegmentRef(key);
+  assertFits(namespacePathPart(key.namespace), 0);
+  assertFits(storageObjectFilename(key.segment, key.generation), TEMP_SUFFIX_BYTES);
+}
+function assertRegistryNamesFit(ref) {
+  validateSegmentRef(ref);
+  assertFits(namespacePathPart(ref.namespace), 0);
+  assertFits(`${encodeNameForPath(ref.segment)}${REGISTRY_SUFFIX}`, TEMP_SUFFIX_BYTES);
+}
+function segmentsDir(root, ref) {
+  validateSegmentRef(ref);
+  return join(root, namespacePathPart(ref.namespace), "segments");
+}
+function storageObjectPath(root, key) {
+  validateSegmentRef(key);
+  requireInteger(key.generation, { min: 0, what: "generation" });
+  return join(
+    segmentsDir(root, { segment: key.segment, namespace: key.namespace }),
+    storageObjectFilename(key.segment, key.generation)
+  );
+}
+function storageObjectFilename(segment, generation) {
+  return `${encodeNameForPath(segment)}.${generation}.crbm`;
+}
+function parseGeneration(segment, filename) {
+  const prefix = `${encodeNameForPath(segment)}.`;
+  const suffix = ".crbm";
+  if (!filename.startsWith(prefix) || !filename.endsWith(suffix)) return null;
+  const middle = filename.slice(prefix.length, filename.length - suffix.length);
+  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
+  const gen = Number(middle);
+  return Number.isSafeInteger(gen) ? gen : null;
+}
+var REGISTRY_SUFFIX = ".reg";
+function registryDir(root, namespace) {
+  if (namespace !== void 0) validateSegmentRef({ segment: "x", namespace });
+  return join(root, namespacePathPart(namespace), "registry");
+}
+function registryRowPath(root, ref) {
+  validateSegmentRef(ref);
+  return join(
+    registryDir(root, ref.namespace),
+    `${encodeNameForPath(ref.segment)}${REGISTRY_SUFFIX}`
+  );
+}
+function parseRegistryRow(filename) {
+  if (!filename.endsWith(REGISTRY_SUFFIX)) return null;
+  const stem = filename.slice(0, filename.length - REGISTRY_SUFFIX.length);
+  const segment = decodeNameFromPath(stem);
+  if (encodeNameForPath(segment) !== stem) return null;
+  try {
+    validateSegmentRef({ segment });
+  } catch {
+    return null;
+  }
+  return segment;
+}
+function parseNamespaceDir(entry) {
+  if (entry === DEFAULT_NAMESPACE) return { namespace: void 0 };
+  const namespace = decodeNameFromPath(entry);
+  if (encodeNameForPath(namespace) !== entry) return null;
+  try {
+    validateSegmentRef({ segment: "x", namespace });
+  } catch {
+    return null;
+  }
+  return { namespace };
+}
+
+// src/drivers/localfs/exact-case.ts
+import { readdir, realpath, stat } from "node:fs/promises";
+import { dirname as dirname2, join as join3, parse, relative, resolve, sep } from "node:path";
+
+// src/drivers/localfs/fs-util.ts
+import { constants as FS } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, opendir, open, unlink } from "node:fs/promises";
+import { dirname, join as join2 } from "node:path";
+var isCode = (err, code) => err instanceof Error && err.code === code;
+var isAbsent = (err) => isCode(err, "ENOENT") || isCode(err, "ENOTDIR") || isCode(err, "ENAMETOOLONG");
+var TRANSIENT_FS_CODES = /* @__PURE__ */ new Set(["EBUSY", "EAGAIN", "EMFILE", "ENFILE", "ETIMEDOUT"]);
+var isFsTransient = (err) => err instanceof Error && TRANSIENT_FS_CODES.has(err.code ?? "");
+var mapFsError = (err) => isFsTransient(err) ? new TransientError(`transient filesystem fault: ${err.code}`, { cause: err }) : err;
+var O_NOFOLLOW = FS.O_NOFOLLOW ?? 0;
+var FILE_MODE = 384;
+var DIR_MODE = 448;
+async function fsyncDir(dir) {
+  try {
+    const handle = await open(dir, "r");
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  } catch {
+  }
+}
+async function writeAll(handle, bytes) {
+  let offset = 0;
+  while (offset < bytes.length) {
+    const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset);
+    if (bytesWritten <= 0) {
+      throw Object.assign(new Error("a write made no progress: the device is full"), {
+        code: "ENOSPC"
+      });
+    }
+    offset += bytesWritten;
+  }
+}
+async function makeDirs(dir, top) {
+  if (!parentsMade.has(top)) {
+    await mkdir(dirname(top), { recursive: true });
+    parentsMade.add(top);
+  }
+  await mkdir(dir, { recursive: true, mode: DIR_MODE });
+}
+var parentsMade = /* @__PURE__ */ new Set();
+var tempPathFor = (finalPath) => `${finalPath}.${randomUUID()}.tmp`;
+var TEMP_NAME = /\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/;
+var ORPHAN_TEMP_AGE_MS = 24 * 60 * 60 * 1e3;
+var SWEEP_INTERVAL_MS = 60 * 60 * 1e3;
+var lastSwept = /* @__PURE__ */ new Map();
+async function sweepOrphanTemps(dir, now = Date.now()) {
+  const last = lastSwept.get(dir);
+  if (last !== void 0 && now - last < SWEEP_INTERVAL_MS) return;
+  lastSwept.set(dir, now);
+  try {
+    const entries = await opendir(dir);
+    for await (const entry of entries) {
+      if (!TEMP_NAME.test(entry.name)) continue;
+      const path = join2(dir, entry.name);
+      const info = await lstat(path).catch(() => void 0);
+      if (info?.isFile() === true && info.mtimeMs < now - ORPHAN_TEMP_AGE_MS) {
+        await unlink(path).catch(() => {
+        });
+      }
+    }
+  } catch {
+  }
+}
+
+// src/drivers/localfs/exact-case.ts
+function firstCaseDifference(expected, actual) {
+  const shared = Math.min(expected.length, actual.length);
+  for (let i = 0; i < shared; i++) {
+    const want = expected[i];
+    const have = actual[i];
+    if (want !== have) return want.toLowerCase() === have.toLowerCase() ? i : -1;
+  }
+  return -1;
+}
+var swapCase = (s) => [...s].map((c) => c === c.toLowerCase() ? c.toUpperCase() : c.toLowerCase()).join("");
+var components = (path) => path.split(sep).filter((c) => c !== "");
+function caseVariantError() {
+  return new ValidationError(
+    "names differ only by case on a case-insensitive filesystem: a name that differs only by case from one already stored is the same file here, so it is refused rather than written over"
+  );
+}
+var ExactCase = class {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  /** `undefined` until the root holds an entry to try; then fixed, as a filesystem does not change its mind. */
+  insensitive;
+  /**
+   * Whether the root's filesystem folds case, learned from an entry already in the root: the entry's name with its
+   * case swapped is the same file or it is not. An empty or absent root holds nothing to alias, so it is not
+   * insensitive yet, and is looked at again on the next call.
+   */
+  async foldsCase() {
+    if (this.insensitive !== void 0) return this.insensitive;
+    let names;
+    try {
+      names = await readdir(this.root);
+    } catch (err) {
+      if (isAbsent(err)) return this.foldsAtAncestor();
+      throw err;
+    }
+    for (const name of names) {
+      const swapped = swapCase(name);
+      if (swapped === name) continue;
+      const own = await stat(join3(this.root, name), { bigint: true }).catch(() => void 0);
+      if (own === void 0) continue;
+      const other = await stat(join3(this.root, swapped), { bigint: true }).catch(() => void 0);
+      this.insensitive = other !== void 0 && other.ino === own.ino && other.dev === own.dev;
+      return this.insensitive;
+    }
+    return this.foldsAtAncestor();
+  }
+  /**
+   * The same question asked of the root's own name, or the nearest existing directory above it, when the root holds
+   * nothing to try: a root with no entries has none to alias yet, but two names created at once still would. Not
+   * remembered, since it is the volume above the root that answers.
+   */
+  async foldsAtAncestor() {
+    let dir = resolve(this.root);
+    for (; ; ) {
+      const top = parse(dir).root;
+      const parts = components(relative(top, dir));
+      let at = parts.length - 1;
+      while (at >= 0 && swapCase(parts[at]) === parts[at]) at--;
+      if (at === -1) return false;
+      const swapped = [...parts];
+      swapped[at] = swapCase(parts[at]);
+      let own;
+      try {
+        own = await stat(dir, { bigint: true });
+      } catch (err) {
+        if (!isAbsent(err)) return false;
+        const parent = dirname2(dir);
+        if (parent === dir) return false;
+        dir = parent;
+        continue;
+      }
+      const other = await stat(join3(top, ...swapped), { bigint: true }).catch(() => void 0);
+      return other !== void 0 && other.ino === own.ino && other.dev === own.dev;
+    }
+  }
+  /** Whether the root's filesystem folds case: names that differ only by case are one file there. */
+  folds() {
+    return this.foldsCase();
+  }
+  /**
+   * `true` when `path` (inside the root) is, on disk, a path whose name differs only by case from the one given:
+   * the deepest part of it that exists is resolved to its real name and compared exactly. A path that does not exist
+   * yet, or that nothing differs from, is `false`.
+   */
+  async differs(path) {
+    if (!await this.foldsCase()) return false;
+    const rootAbs = resolve(this.root);
+    let probe = resolve(path);
+    let real;
+    for (; ; ) {
+      if (probe === rootAbs || !relative(rootAbs, probe) || relative(rootAbs, probe).startsWith("..")) {
+        return false;
+      }
+      try {
+        real = await realpath(probe);
+        break;
+      } catch (err) {
+        if (!isAbsent(err)) throw err;
+        probe = dirname2(probe);
+      }
+    }
+    const realRoot = await realpath(rootAbs).catch(() => void 0);
+    if (realRoot === void 0) return false;
+    const actual = relative(realRoot, real);
+    if (actual.startsWith("..")) return false;
+    return firstCaseDifference(components(relative(rootAbs, probe)), components(actual)) !== -1;
+  }
+  /** Refuse a write to `path` when its real name differs from it only by case. */
+  async refuseVariant(path) {
+    if (await this.differs(path)) throw caseVariantError();
+  }
+};
+
+// src/drivers/localfs/storage.ts
+async function readWhole(handle, key, length, offset) {
+  const buf = new Uint8Array(length);
+  let filled = 0;
+  while (filled < length) {
+    const { bytesRead } = await handle.read(buf, filled, length - filled, offset + filled);
+    if (bytesRead === 0) {
+      throw new IntegrityError(
+        `short read of ${key.segment}.${key.generation}: wanted ${length}B at ${offset}, got ${filled}B`
+      );
+    }
+    filled += bytesRead;
+  }
+  return buf;
+}
+var LocalFsStorageDriver = class {
+  /**
+   * `options.privateRoot` is the directory this one lives under, from which down directories are created private; it
+   * defaults to `root`.
+   */
+  constructor(root, options = {}) {
+    this.root = root;
+    this.options = options;
+    this.exactCase = new ExactCase(root);
+  }
+  root;
+  options;
+  exactCase;
+  capabilities() {
+    return {
+      rangeRead: true,
+      maxObjectBytes: Number.MAX_SAFE_INTEGER,
+      conditionalPut: false,
+      conditionalDelete: false
+    };
+  }
+  async putImmutable(key, write) {
+    const finalPath = storageObjectPath(this.root, key);
+    assertStorageNamesFit(key);
+    await this.exactCase.refuseVariant(finalPath);
+    await makeDirs(dirname3(finalPath), this.options.privateRoot ?? this.root);
+    void sweepOrphanTemps(dirname3(finalPath));
+    const tmpPath = tempPathFor(finalPath);
+    const handle = await open2(
+      tmpPath,
+      FS2.O_CREAT | FS2.O_EXCL | FS2.O_WRONLY | O_NOFOLLOW,
+      FILE_MODE
+    );
+    const hash = createHash2("sha256");
+    let size = 0;
+    const sink = {
+      async write(bytes) {
+        await writeAll(handle, bytes);
+        hash.update(bytes);
+        size += bytes.length;
+      }
+    };
+    try {
+      await write(sink);
+      await handle.sync();
+    } catch (err) {
+      await handle.close().catch(() => {
+      });
+      await unlink2(tmpPath).catch(() => {
+      });
+      throw mapFsError(err);
+    }
+    await handle.close();
+    try {
+      await link(tmpPath, finalPath);
+    } catch (err) {
+      await unlink2(tmpPath).catch(() => {
+      });
+      if (isCode(err, "ENOENT")) {
+        throw new TransientError(
+          `the temporary file of ${key.segment}.${key.generation} was removed mid-write`,
+          {
+            cause: err
+          }
+        );
+      }
+      if (isCode(err, "EEXIST")) {
+        throw new WriteConflictError(
+          `generation already exists (write-once): ${key.segment}.${key.generation}`
+        );
+      }
+      throw mapFsError(err);
+    }
+    await unlink2(tmpPath).catch(() => {
+    });
+    await fsyncDir(dirname3(finalPath));
+    return { size, sha256: hash.digest("hex") };
+  }
+  async getRange(key, offset, length) {
+    requireInteger(offset, { min: 0, what: "range offset" });
+    requireInteger(length, { min: 0, what: "range length" });
+    const handle = await this.openRead(key);
+    try {
+      const { size } = await handle.stat();
+      if (offset + length > size) {
+        throw new ValidationError(
+          `range [${offset}, ${offset + length}) out of bounds for ${size}B`
+        );
+      }
+      return await readWhole(handle, key, length, offset);
+    } finally {
+      await handle.close();
+    }
+  }
+  async getTail(key, maxBytes) {
+    checkTailLength(maxBytes);
+    const handle = await this.openRead(key);
+    try {
+      const { size } = await handle.stat();
+      const take = Math.min(Math.max(maxBytes, 0), size);
+      return { bytes: await readWhole(handle, key, take, size - take), size };
+    } finally {
+      await handle.close();
+    }
+  }
+  /**
+   * Idempotent. Ignores `options.ifVersion`, as `conditionalDelete: false` says: see the note on the class for why it
+   * cannot apply one. The parameter is declared so that a wrapper of this driver can hand the port's options on.
+   */
+  async delete(key, options) {
+    checkDeleteOptions(options);
+    const path = storageObjectPath(this.root, key);
+    if (await this.exactCase.differs(path)) return;
+    await unlink2(path).catch((err) => {
+      if (!isAbsent(err)) throw mapFsError(err);
+    });
+  }
+  async *list(ref) {
+    const dir = segmentsDir(this.root, ref);
+    if (await this.exactCase.differs(dir)) return;
+    let names;
+    try {
+      names = await readdir2(dir);
+    } catch (err) {
+      if (isAbsent(err)) return;
+      throw mapFsError(err);
+    }
+    for (const name of names) {
+      const generation = parseGeneration(ref.segment, name);
+      if (generation !== null) {
+        yield { namespace: ref.namespace, segment: ref.segment, generation };
+      }
+    }
+  }
+  async openRead(key) {
+    const path = storageObjectPath(this.root, key);
+    if (await this.exactCase.differs(path)) {
+      throw new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
+    }
+    try {
+      return await open2(path, FS2.O_RDONLY | O_NOFOLLOW);
+    } catch (err) {
+      if (isAbsent(err)) {
+        throw new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
+      }
+      if (isCode(err, "ELOOP")) {
+        throw new NotFoundError(
+          `generation path is a symlink, refusing: ${key.segment}.${key.generation}`
+        );
+      }
+      throw mapFsError(err);
+    }
+  }
+};
+
+// src/drivers/localfs/registry.ts
+import { constants as FS3 } from "node:fs";
+import { open as open3, opendir as opendir2, readdir as readdir3, realpath as realpath2, rename, unlink as unlink3 } from "node:fs/promises";
+import { basename, dirname as dirname4, join as join4, relative as relative2, resolve as resolve2 } from "node:path";
+var DEFAULT_MAX_ROW_BYTES = 1 * 1024 * 1024;
+var rowChains = /* @__PURE__ */ new Map();
+async function rowLockKey(path) {
+  const abs = resolve2(path);
+  const tail = [basename(abs)];
+  let dir = dirname4(abs);
+  for (; ; ) {
+    try {
+      return join4(await realpath2(dir), ...tail);
+    } catch (err) {
+      const parent = dirname4(dir);
+      if (!isAbsent(err) || parent === dir) throw mapFsError(err);
+      tail.unshift(basename(dir));
+      dir = parent;
+    }
+  }
+}
+var LocalFsRegistryDriver = class {
+  constructor(root, options = {}) {
+    this.root = root;
+    this.options = options;
+    this.exactCase = new ExactCase(root);
+    this.now = options.now ?? (() => Date.now());
+    this.entropy = options.entropy ?? webCryptoEntropy;
+  }
+  root;
+  options;
+  now;
+  entropy;
+  exactCase;
+  /**
+   * `conditionalDelete`: a delete reads the row, checks it, and unlinks it under the row's lock, which every writer on
+   * the root in this process takes, so no write can land between the check and the unlink.
+   */
+  capabilities() {
+    return entropyIsAvailable(this.entropy) ? { strongRead: true, conditionalDelete: true } : { strongRead: true, canWrite: false, conditionalDelete: true };
+  }
+  /** Every write reports its token to `onToken` before the row's file is written. */
+  get reportsWriteTokens() {
+    return true;
+  }
+  async get(ref) {
+    const env = await this.readRow(registryRowPath(this.root, ref), ref);
+    return env && !env.deleted ? env.record : null;
+  }
+  async create(ref, record, options) {
+    checkRegistryWriteOptions(options);
+    const checked = validateNewRegistryRecord(record);
+    const path = registryRowPath(this.root, ref);
+    assertRegistryNamesFit(ref);
+    return this.withRowLock(path, async () => {
+      const current = await this.readRow(path, ref);
+      if (current !== null && !current.deleted) {
+        throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
+      }
+      const token = newIncarnationToken(this.entropy, current?.record);
+      options?.onToken?.(token);
+      await this.writeRow(path, recordFromNew(ref, checked, this.now(), token));
+      return { token };
+    });
+  }
+  /**
+   * A caller's `held` row (see `RegistryWriteOptions`) has no read to spare here: the row's file is read under its lock and its token compared
+   * there, a local read and no request, so a stale one fails exactly as a lost race does.
+   */
+  async compareAndSwap(ref, expected, patch, options) {
+    checkRegistryWriteOptions(options);
+    const checked = validateRegistryPatch(patch);
+    const path = registryRowPath(this.root, ref);
+    assertRegistryNamesFit(ref);
+    return this.withRowLock(path, async () => {
+      const current = await this.readRow(path, ref);
+      if (current === null || current.deleted || current.record.token !== expected) {
+        throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+      }
+      const token = nextRegistryToken(current.record, this.entropy);
+      options?.onToken?.(token);
+      await this.writeRow(path, applyRegistryPatch(current.record, checked, this.now(), token));
+      return { token };
+    });
+  }
+  async *list(namespace) {
+    for (const ns of await this.namespaceDirs(namespace)) {
+      const dir = registryDir(this.root, ns);
+      if (await this.exactCase.differs(dir)) continue;
+      let entries;
+      try {
+        entries = await opendir2(dir);
+      } catch (err) {
+        if (isAbsent(err)) continue;
+        throw mapFsError(err);
+      }
+      for await (const entry of entries) {
+        const segment = parseRegistryRow(entry.name);
+        if (segment === null) continue;
+        const ref = { namespace: ns, segment };
+        const env = await this.readRow(registryRowPath(this.root, ref), ref);
+        if (env && !env.deleted) yield env.record;
+      }
+    }
+  }
+  async delete(ref, expected) {
+    const path = registryRowPath(this.root, ref);
+    return this.withRowLock(path, async () => {
+      const current = await this.readRow(path, ref);
+      if (expected !== void 0) {
+        if (current === null || current.deleted || current.record.token !== expected) {
+          throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+        }
+      } else if (current === null || current.deleted) {
+        return;
+      }
+      await this.unlinkRow(path);
+    });
+  }
+  /** Remove a row's file and make the removal durable (fsync the directory). */
+  async unlinkRow(path) {
+    try {
+      await unlink3(path);
+    } catch (err) {
+      if (!isCode(err, "ENOENT")) throw mapFsError(err);
+    }
+    await fsyncDir(dirname4(path));
+  }
+  /** Namespaces to scan: just the one requested, or every namespace dir under the root. */
+  async namespaceDirs(namespace) {
+    if (namespace !== void 0) return [namespace];
+    let entries;
+    try {
+      entries = await readdir3(this.root);
+    } catch (err) {
+      if (isCode(err, "ENOENT")) return [];
+      throw mapFsError(err);
+    }
+    const namespaces = [];
+    for (const entry of entries) {
+      const parsed = parseNamespaceDir(entry);
+      if (parsed !== null) namespaces.push(parsed.namespace);
+    }
+    return namespaces;
+  }
+  /** Read the row at `path`, which must be the row of `ref`: one that names another segment is refused. */
+  async readRow(path, ref) {
+    let handle;
+    try {
+      if (await this.exactCase.differs(path)) return null;
+      handle = await open3(path, FS3.O_RDONLY | O_NOFOLLOW);
+    } catch (err) {
+      if (isAbsent(err) || isCode(err, "ELOOP")) return null;
+      throw mapFsError(err);
+    }
+    try {
+      const { size } = await handle.stat();
+      if (size > DEFAULT_MAX_ROW_BYTES) {
+        throw new IntegrityError(`registry row ${size}B exceeds cap ${DEFAULT_MAX_ROW_BYTES}B`);
+      }
+      const text = (await handle.readFile()).toString("utf8");
+      return parseRegistryEnvelope(text, relative2(this.root, path), ref);
+    } finally {
+      await handle.close();
+    }
+  }
+  async writeRow(path, record) {
+    await this.exactCase.refuseVariant(path);
+    await makeDirs(dirname4(path), this.options.privateRoot ?? this.root);
+    void sweepOrphanTemps(dirname4(path));
+    const out = Buffer.from(serializeRegistryEnvelope({ deleted: false, record }), "utf8");
+    if (out.length > DEFAULT_MAX_ROW_BYTES) {
+      throw new ValidationError(
+        `registry row ${out.length}B exceeds cap ${DEFAULT_MAX_ROW_BYTES}B`
+      );
+    }
+    const tmp = tempPathFor(path);
+    let handle;
+    try {
+      handle = await open3(tmp, FS3.O_CREAT | FS3.O_EXCL | FS3.O_WRONLY | O_NOFOLLOW, FILE_MODE);
+    } catch (err) {
+      throw mapFsError(err);
+    }
+    try {
+      await writeAll(handle, out);
+      await handle.sync();
+    } catch (err) {
+      await handle.close().catch(() => {
+      });
+      await unlink3(tmp).catch(() => {
+      });
+      throw mapFsError(err);
+    }
+    await handle.close();
+    await rename(tmp, path).catch(async (err) => {
+      await unlink3(tmp).catch(() => {
+      });
+      if (isCode(err, "ENOENT")) {
+        throw new TransientError("the temporary file of a registry row was removed mid-write", {
+          cause: err
+        });
+      }
+      throw mapFsError(err);
+    });
+    await fsyncDir(dirname4(path));
+  }
+  /** Serialize callbacks for a row so read-modify-write is atomic across every instance in the process. */
+  async withRowLock(path, fn) {
+    const resolved = await rowLockKey(path);
+    const key = await this.exactCase.folds() ? resolved.toLowerCase() : resolved;
+    const prev = rowChains.get(key) ?? Promise.resolve();
+    const result = prev.then(fn, fn);
+    const tail = result.then(
+      () => void 0,
+      () => void 0
+    );
+    rowChains.set(key, tail);
+    void tail.then(() => {
+      if (rowChains.get(key) === tail) rowChains.delete(key);
+    });
+    return result;
+  }
+};
+
+// src/drivers/backends.ts
+var CLOCK_OPTION_KEYS = ["now"];
+var MemoryStorage = class {
+  storage;
+  registry;
+  /**
+   * Builds an empty in-process backend. `options.now` is the clock for the registry's timestamps, `Date.now` by
+   * default; any other option throws `ValidationError`.
+   */
+  constructor(options = {}) {
+    refuseUnknownOptions("MemoryStorage", options, CLOCK_OPTION_KEYS);
+    checkNow("MemoryStorage", options.now);
+    this.storage = new MemoryStorageDriver();
+    this.registry = new MemoryRegistryDriver(options.now === void 0 ? {} : { now: options.now });
+    brandAsBackend(this);
+  }
+  /** Nothing to check: process memory has no lifecycle rules. */
+  checkLifecycle() {
+    return Promise.resolve({
+      status: "ok",
+      detail: "MemoryStorage keeps its objects in process memory, which has no lifecycle rules"
+    });
+  }
+};
+var LocalFsStorage = class {
+  /**
+   * Builds a backend rooted at `root`, a non-empty directory path. `options.now` is the clock for the registry's
+   * timestamps, `Date.now` by default; any other option throws `ValidationError`.
+   */
+  constructor(root, options = {}) {
+    this.root = root;
+    if (typeof root !== "string" || root.trim().length === 0) {
+      throw new ValidationError(
+        `LocalFsStorage needs a root directory: a non-empty string, got ${root === "" ? "an empty string" : typeof root}`
+      );
+    }
+    refuseUnknownOptions("LocalFsStorage", options, CLOCK_OPTION_KEYS);
+    checkNow("LocalFsStorage", options.now);
+    this.storage = new LocalFsStorageDriver(join5(root, "storage"), { privateRoot: root });
+    this.registry = new LocalFsRegistryDriver(
+      join5(root, "registry"),
+      options.now === void 0 ? { privateRoot: root } : { now: options.now, privateRoot: root }
+    );
+    brandAsBackend(this);
+  }
+  root;
+  storage;
+  registry;
+  /** Nothing to check: a local directory has no lifecycle rules. */
+  checkLifecycle() {
+    return Promise.resolve({
+      status: "ok",
+      detail: "LocalFsStorage keeps its objects in a local directory, which has no lifecycle rules"
+    });
+  }
+};
+
+// src/drivers/crypto.ts
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+var UTF8 = new TextEncoder();
+var KEY_BYTES = 32;
+var NONCE_BYTES = 12;
+var TAG_BYTES = 16;
+var isBytes = (v) => Object.prototype.toString.call(v) === "[object Uint8Array]";
+function ownKey(key) {
+  const own = Buffer.alloc(key.length);
+  own.set(key);
+  return own;
+}
+var NodeAead = class {
+  key;
+  constructor(key) {
+    if (!isBytes(key))
+      throw new ValidationError("AEAD key must be a Uint8Array of key bytes, not text");
+    if (key.length !== KEY_BYTES)
+      throw new ValidationError(`AEAD key must be ${KEY_BYTES} bytes, got ${key.length}`);
+    this.key = ownKey(key);
+  }
+  seal(plaintext, aad) {
+    const nonce = randomBytes(NONCE_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", this.key, nonce);
+    cipher.setAAD(aad);
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return { nonce, ciphertext, tag: cipher.getAuthTag() };
+  }
+  open(sealed, aad) {
+    if (sealed.nonce.length !== NONCE_BYTES || sealed.tag.length !== TAG_BYTES)
+      throw new IntegrityError("AEAD nonce/tag have the wrong length");
+    const decipher = createDecipheriv("aes-256-gcm", this.key, sealed.nonce);
+    decipher.setAAD(aad);
+    decipher.setAuthTag(Buffer.from(sealed.tag));
+    try {
+      return Buffer.concat([decipher.update(sealed.ciphertext), decipher.final()]);
+    } catch {
+      throw new IntegrityError(
+        "AEAD authentication failed (wrong key, tampered data, or wrong context)"
+      );
+    }
+  }
+};
+function wrapKey(dek, kek, keyId) {
+  const sealed = new NodeAead(kek).seal(dek, UTF8.encode(keyId));
+  return Buffer.concat([sealed.nonce, sealed.ciphertext, sealed.tag]).toString("base64");
+}
+function unwrapKey(wrapped, kek, keyId) {
+  const blob = Buffer.from(wrapped, "base64");
+  if (blob.length < NONCE_BYTES + TAG_BYTES)
+    throw new IntegrityError("wrapped DEK is too short to be valid");
+  const nonce = blob.subarray(0, NONCE_BYTES);
+  const tag = blob.subarray(blob.length - TAG_BYTES);
+  const ciphertext = blob.subarray(NONCE_BYTES, blob.length - TAG_BYTES);
+  return new NodeAead(kek).open({ nonce, ciphertext, tag }, UTF8.encode(keyId));
+}
+var InProcessKeystore = class {
+  keys;
+  activeKeyId;
+  recoveryKeyId;
+  /**
+   * Builds a keystore from `options`; throws `ValidationError` for no options object, an option it does not take
+   * (a misspelt `recoveryKeyId` would otherwise leave no recovery wrapping), a `keys` that is not an object, an
+   * `activeKeyId` or `recoveryKeyId` that is not a string, no keys, a key given as text rather than a
+   * `Uint8Array`, a key that is not 32 bytes, or an `activeKeyId` or `recoveryKeyId` that is not in `keys`. A
+   * `recoveryKeyId` equal to `activeKeyId` means no recovery key.
+   */
+  constructor(options) {
+    refuseUnknownOptions("InProcessKeystore", options, ["keys", "activeKeyId", "recoveryKeyId"]);
+    const keys = options.keys;
+    const proto = keys === null || typeof keys !== "object" ? null : Object.getPrototypeOf(keys);
+    if (keys === null || typeof keys !== "object" || proto !== Object.prototype && proto !== null) {
+      throw new ValidationError(
+        "InProcessKeystore: `keys` must be a plain object of key id to 32-byte Uint8Array KEK, not a Map or an array"
+      );
+    }
+    if (typeof options.activeKeyId !== "string") {
+      throw new ValidationError(
+        "InProcessKeystore: `activeKeyId` must be a string naming one of `keys`"
+      );
+    }
+    if (options.recoveryKeyId !== void 0 && typeof options.recoveryKeyId !== "string") {
+      throw new ValidationError(
+        "InProcessKeystore: `recoveryKeyId` must be a string naming one of `keys`, or absent for none"
+      );
+    }
+    const entries = Object.entries(keys);
+    if (entries.length === 0) throw new ValidationError("keystore needs at least one KEK");
+    for (const [id, k] of entries) {
+      if (!isBytes(k))
+        throw new ValidationError(`KEK "${id}" must be a Uint8Array of key bytes, not text`);
+      if (k.length !== KEY_BYTES)
+        throw new ValidationError(`KEK "${id}" must be ${KEY_BYTES} bytes, got ${k.length}`);
+    }
+    this.keys = new Map(entries.map(([id, k]) => [id, ownKey(k)]));
+    if (!this.keys.has(options.activeKeyId))
+      throw new ValidationError(`activeKeyId "${String(options.activeKeyId)}" is not in keys`);
+    if (options.recoveryKeyId !== void 0 && !this.keys.has(options.recoveryKeyId))
+      throw new ValidationError(`recoveryKeyId "${String(options.recoveryKeyId)}" is not in keys`);
+    this.activeKeyId = options.activeKeyId;
+    this.recoveryKeyId = options.recoveryKeyId === options.activeKeyId ? void 0 : options.recoveryKeyId;
+  }
+  // async to satisfy the IKeystore seam (a KMS adapter awaits a network call here); the in-process path is
+  // synchronous, but staying async keeps unwrap failures as rejections, matching a remote keystore.
+  async createDek() {
+    const dek = randomBytes(KEY_BYTES);
+    const ids = this.recoveryKeyId ? [this.activeKeyId, this.recoveryKeyId] : [this.activeKeyId];
+    const wrapped = ids.map((keyId) => ({
+      keyId,
+      wrapped: wrapKey(dek, this.keys.get(keyId), keyId)
+    }));
+    return { wrapped, aead: new NodeAead(dek) };
+  }
+  // async for the same reason as createDek — a synchronous unwrap failure surfaces as a promise rejection.
+  async openDek(wrapped) {
+    let anyKekHeld = false;
+    let lastUnwrapError;
+    for (const w of wrapped) {
+      const kek = this.keys.get(w.keyId);
+      if (kek === void 0) continue;
+      anyKekHeld = true;
+      try {
+        return new NodeAead(unwrapKey(w.wrapped, kek, w.keyId));
+      } catch (err) {
+        lastUnwrapError = err;
+      }
+    }
+    if (anyKekHeld) throw lastUnwrapError;
+    const need = wrapped.map((w) => w.keyId).join(", ") || "(none)";
+    throw new KeyUnavailableError(
+      `no held KEK can unwrap this DEK \u2014 the wrappings reference [${need}]. Restore the missing KEK (or its recovery KEK), or rebuild the segment from source.`
+    );
+  }
+};
+export {
+  InProcessKeystore,
+  LocalFsStorage,
+  MemoryStorage,
+  NodeAead
+};
+//# sourceMappingURL=node.js.map