@noy-db/hub 0.2.0-pre.2 → 0.2.0-pre.21

package/dist/blobs/index.cjs

@@ -90,7 +90,9 @@ __export(crypto_exports, {
   generateSalt: () => generateSalt,
   hmacSha256Hex: () => hmacSha256Hex,
   sha256Hex: () => sha256Hex,
+  unwrapCek: () => unwrapCek,
   unwrapKey: () => unwrapKey,
+  wrapCek: () => wrapCek,
   wrapKey: () => wrapKey
 });
 async function deriveKey(passphrase, salt) {
@@ -141,6 +143,39 @@ async function unwrapKey(wrappedBase64, kek) {
     throw new InvalidKeyError();
   }
 }
+async function asKwKey(dek) {
+  const rawDek = await subtle.exportKey("raw", dek);
+  const hkdfKey = await subtle.importKey("raw", rawDek, "HKDF", false, ["deriveBits"]);
+  const salt = new TextEncoder().encode("noydb-cek-wrap");
+  const info = new TextEncoder().encode("v1");
+  const bits = await subtle.deriveBits(
+    { name: "HKDF", hash: "SHA-256", salt, info },
+    hkdfKey,
+    KEY_BITS
+  );
+  return subtle.importKey("raw", bits, "AES-KW", false, ["wrapKey", "unwrapKey"]);
+}
+async function wrapCek(cek, dek) {
+  const kw = await asKwKey(dek);
+  const wrapped = await subtle.wrapKey("raw", cek, kw, "AES-KW");
+  return bufferToBase64(wrapped);
+}
+async function unwrapCek(wrappedBase64, dek) {
+  const kw = await asKwKey(dek);
+  try {
+    return await subtle.unwrapKey(
+      "raw",
+      base64ToBuffer(wrappedBase64),
+      kw,
+      "AES-KW",
+      { name: "AES-GCM", length: KEY_BITS },
+      true,
+      ["encrypt", "decrypt"]
+    );
+  } catch {
+    throw new InvalidKeyError();
+  }
+}
 async function encrypt(plaintext, dek) {
   const iv = generateIV();
   const encoded = new TextEncoder().encode(plaintext);
@@ -362,7 +397,9 @@ __export(blobs_exports, {
   createExportBlobsHandle: () => createExportBlobsHandle,
   detectMagic: () => detectMagic,
   detectMimeType: () => detectMimeType,
+  importExternalObjects: () => importExternalObjects,
   isPreCompressed: () => isPreCompressed,
+  memoryObjectProjection: () => memoryObjectProjection,
   runCompaction: () => runCompaction,
   withBlobs: () => withBlobs
 });
@@ -373,6 +410,11 @@ var NOYDB_FORMAT_VERSION = 1;
 
 // src/blobs/blob-set.ts
 init_crypto();
+
+// src/record-keys/index.ts
+init_crypto();
+
+// src/blobs/blob-set.ts
 init_errors();
 
 // src/blobs/mime-magic.ts
@@ -600,11 +642,8 @@ async function compressBytes(data) {
   if (typeof CompressionStream === "undefined") {
     return { bytes: data, algorithm: "none" };
   }
-  const cs = new CompressionStream("gzip");
-  const writer = cs.writable.getWriter();
-  await writer.write(data);
-  await writer.close();
-  const buf = await new Response(cs.readable).arrayBuffer();
+  const piped = new Response(data).body.pipeThrough(new CompressionStream("gzip"));
+  const buf = await new Response(piped).arrayBuffer();
   return { bytes: new Uint8Array(buf), algorithm: "gzip" };
 }
 async function decompressBytes(data) {
@@ -613,11 +652,8 @@ async function decompressBytes(data) {
       "[noy-db] DecompressionStream not available \u2014 cannot decompress blob chunk"
     );
   }
-  const ds = new DecompressionStream("gzip");
-  const writer = ds.writable.getWriter();
-  await writer.write(data);
-  await writer.close();
-  const buf = await new Response(ds.readable).arrayBuffer();
+  const piped = new Response(data).body.pipeThrough(new DecompressionStream("gzip"));
+  const buf = await new Response(piped).arrayBuffer();
   return new Uint8Array(buf);
 }
 function concatChunks(chunks) {
@@ -642,6 +678,10 @@ var BlobSet = class {
   encrypted;
   userId;
   maxBlobBytes;
+  erasableBlobs;
+  debugPlaintext;
+  objectStore;
+  blobFields;
   constructor(opts) {
     this.store = opts.store;
     this.vault = opts.vault;
@@ -651,6 +691,24 @@ var BlobSet = class {
     this.encrypted = opts.encrypted;
     this.userId = opts.userId;
     this.maxBlobBytes = opts.maxBlobBytes;
+    this.erasableBlobs = opts.erasableBlobs === true;
+    this.debugPlaintext = opts.debugPlaintext === true;
+    this.objectStore = opts.objectStore;
+    this.blobFields = opts.blobFields;
+  }
+  /**
+   * Resolve the key the blob's CHUNKS are encrypted under.
+   *
+   * - `_cek` present (erasable blob) → unwrap the per-blob content CEK under
+   *   the `_blob` DEK. Deleting the BlobObject (at `refCount → 0`) makes this
+   *   key unrecoverable → the chunks are crypto-shredded.
+   * - `_cek` absent (legacy) → the `_blob` DEK encrypts chunks directly.
+   * - unencrypted vault → `null` (chunks stored as plaintext base64).
+   */
+  async resolveChunkKey(blob) {
+    if (!this.encrypted) return null;
+    const blobDEK = await this.getDEK(BLOB_COLLECTION);
+    return blob._cek !== void 0 ? await unwrapCek(blob._cek, blobDEK) : blobDEK;
   }
   /** The internal collection that holds slot metadata for this collection's blobs. */
   get slotsCollection() {
@@ -768,12 +826,163 @@ var BlobSet = class {
       const updated = { ...blob, refCount: blob.refCount + delta };
       try {
         await this.writeBlobObject(updated, version);
+        return updated.refCount;
+      } catch (err) {
+        if (err instanceof ConflictError && attempt < MAX_CAS_RETRIES - 1) continue;
+        throw err;
+      }
+    }
+    throw new ConflictError(-1);
+  }
+  /**
+   * Release `n` references to a blob and reclaim it at refCount 0 (#365 slice 4).
+   *
+   * The single reclaim choke point for every reference-drop path — slot
+   * delete/overwrite, published-version delete, and `forget()` shred — so the
+   * refCount-0 policy is uniform:
+   *  - **erasable blob** (`_cek` present) → delete the `BlobObject` (the SOLE
+   *    copy of the wrapped content CEK → chunks permanently undecryptable) and
+   *    reclaim the chunks. The crypto-shred is EAGER on every path: GDPR erasure
+   *    must not wait on orphan retention.
+   *  - **legacy blob** (no `_cek`) → reclaimed only when `reclaimLegacy` (the
+   *    `forget()` erasure path); otherwise left for deferred GC so the existing
+   *    `BlobLifecyclePolicy.orphanRetentionDays` semantics are preserved.
+   *
+   * @returns `'shredded'` (erasable, refCount 0, chunks dead) · `'retainedShared'`
+   *   (erasable, still referenced) · `'residue'` (legacy — not a crypto-shred).
+   */
+  async releaseRef(eTag, n, reclaimLegacy) {
+    const loaded = await this.loadBlobObject(eTag);
+    if (!loaded) return "shredded";
+    const erasable = loaded.blob._cek !== void 0;
+    const remaining = await this.casUpdateRefCount(eTag, -n);
+    if (remaining > 0) return erasable ? "retainedShared" : "residue";
+    if (erasable || reclaimLegacy) {
+      await this.store.delete(this.vault, BLOB_INDEX_COLLECTION, eTag);
+      for (let i = 0; i < loaded.blob.chunkCount; i++) {
+        await this.store.delete(this.vault, BLOB_CHUNKS_COLLECTION, `${eTag}_${i}`);
+      }
+    }
+    return erasable ? "shredded" : "residue";
+  }
+  /**
+   * Crypto-shred this record's blob attachments (#365 slice 2) — called by
+   * `vault.forget()`.
+   *
+   * For each distinct eTag the record references (a record may attach the same
+   * content under several slot names → several refCount holds): decrement the
+   * blob's refCount by that many. When it reaches 0:
+   *  - **erasable blob** (`_cek` present) → delete the `BlobObject` (the SOLE
+   *    recoverable copy of the wrapped content CEK → chunks permanently
+   *    undecryptable) and reclaim the chunk bytes. This is the crypto-shred.
+   *  - **legacy blob** (no `_cek`) → chunks are under the shared `_blob` DEK and
+   *    stay decryptable until byte-deleted; we delete the orphaned chunks +
+   *    index but report it as residue, not a cryptographic erasure.
+   * When refCount stays > 0 the content legitimately persists for its other
+   * owner — reported as `retainedShared` (or `residue` if legacy).
+   *
+   * Finally drops the record's slot map, severing the subject's link.
+   */
+  async shredAllForRecord() {
+    const { slots } = await this.loadSlots();
+    const slotNames = Object.keys(slots);
+    const shredded = [];
+    const retainedShared = [];
+    const residue = [];
+    if (slotNames.length === 0) return { shredded, retainedShared, residue };
+    const holds = /* @__PURE__ */ new Map();
+    for (const name of slotNames) {
+      const eTag = slots[name].eTag;
+      holds.set(eTag, (holds.get(eTag) ?? 0) + 1);
+    }
+    for (const [eTag, n] of holds) {
+      const outcome = await this.releaseRef(eTag, n, true);
+      if (outcome === "shredded") shredded.push(eTag);
+      else if (outcome === "retainedShared") retainedShared.push(eTag);
+      else residue.push(eTag);
+    }
+    await this.store.delete(this.vault, this.slotsCollection, this.recordId);
+    return { shredded, retainedShared, residue };
+  }
+  /** CAS retry loop for an arbitrary BlobObject mutation. */
+  async casUpdateBlobObject(eTag, mutate) {
+    for (let attempt = 0; attempt < MAX_CAS_RETRIES; attempt++) {
+      const result = await this.loadBlobObject(eTag);
+      if (!result) throw new NotFoundError(`BlobObject ${eTag} not found`);
+      try {
+        await this.writeBlobObject(mutate(result.blob), result.version);
         return;
       } catch (err) {
         if (err instanceof ConflictError && attempt < MAX_CAS_RETRIES - 1) continue;
         throw err;
       }
     }
+    throw new ConflictError(-1);
+  }
+  /**
+   * Migrate this record's LEGACY blobs (no `_cek`, chunks under the shared
+   * `_blob` DEK) to per-blob content CEKs so they become crypto-shreddable
+   * (#365 slice 3). Returns the eTags migrated vs. already-erasable.
+   *
+   * **Explicit maintenance pass** (mirrors the record-CEK migration posture):
+   * re-encrypts the existing compressed chunks IN PLACE under a fresh content
+   * CEK — preserving the eTag, chunkCount, chunkSize, and compression — then
+   * flips the `_cek` discriminant. Crash-safe + idempotent via `_cekPending`:
+   *   1. persist the wrapped content CEK in `_cekPending` (readers ignore it →
+   *      the blob stays readable under the `_blob` DEK; the key survives a crash);
+   *   2. re-encrypt each chunk under the content CEK (a resume reads an
+   *      already-migrated chunk under the content CEK, else under the `_blob` DEK);
+   *   3. promote `_cekPending` → `_cek` (atomic flip). Reads now use the CEK.
+   * A re-run after a crash resumes from whichever phase was reached.
+   *
+   * Dedup-safe: migrating a shared blob (refCount > 1) re-keys it for every
+   * referencer at once; a non-erasable collection still reads it (it unwraps
+   * `_cek` under the `_blob` DEK it holds).
+   */
+  async migrate() {
+    const migrated = [];
+    const alreadyErasable = [];
+    if (!this.encrypted) return { migrated, alreadyErasable };
+    const blobDEK = await this.getDEK(BLOB_COLLECTION);
+    const { slots } = await this.loadSlots();
+    const eTags = new Set(Object.values(slots).map((s) => s.eTag));
+    for (const eTag of eTags) {
+      const loaded = await this.loadBlobObject(eTag);
+      if (!loaded) continue;
+      const blob = loaded.blob;
+      if (blob._cek !== void 0) {
+        alreadyErasable.push(eTag);
+        continue;
+      }
+      let contentCek;
+      if (blob._cekPending !== void 0) {
+        contentCek = await unwrapCek(blob._cekPending, blobDEK);
+      } else {
+        contentCek = await generateDEK();
+        const wrapped = await wrapCek(contentCek, blobDEK);
+        await this.casUpdateBlobObject(eTag, (b) => ({ ...b, _cekPending: wrapped }));
+      }
+      for (let i = 0; i < blob.chunkCount; i++) {
+        let raw;
+        try {
+          raw = await this.readChunk(eTag, i, blob.chunkCount, blobDEK);
+        } catch {
+          raw = await this.readChunk(eTag, i, blob.chunkCount, contentCek);
+        }
+        if (!raw) {
+          throw new NotFoundError(
+            `Blob chunk ${i}/${blob.chunkCount} missing for eTag "${eTag}" during migration`
+          );
+        }
+        await this.writeChunk(eTag, i, blob.chunkCount, raw, contentCek);
+      }
+      await this.casUpdateBlobObject(eTag, (b) => {
+        const { _cekPending, ...rest } = b;
+        return _cekPending === void 0 ? b : { ...rest, _cek: _cekPending };
+      });
+      migrated.push(eTag);
+    }
+    return { migrated, alreadyErasable };
   }
   // ─── Chunk I/O (with AAD binding) ─────────────────────────────────
   async writeChunk(eTag, index, chunkCount, chunk, dek) {
@@ -845,10 +1054,10 @@ var BlobSet = class {
   }
   // ─── Fetch all chunks for a blob ──────────────────────────────────
   async fetchAllChunks(blob) {
-    const blobDEK = this.encrypted ? await this.getDEK(BLOB_COLLECTION) : null;
+    const chunkKey = await this.resolveChunkKey(blob);
     const chunks = [];
     for (let i = 0; i < blob.chunkCount; i++) {
-      const chunk = await this.readChunk(blob.eTag, i, blob.chunkCount, blobDEK);
+      const chunk = await this.readChunk(blob.eTag, i, blob.chunkCount, chunkKey);
       if (!chunk) {
         throw new NotFoundError(
           `Blob chunk ${i}/${blob.chunkCount} missing for eTag "${blob.eTag}" on record "${this.recordId}"`
@@ -873,6 +1082,49 @@ var BlobSet = class {
    *    If overwriting an existing slot, decrements the old eTag's refCount.
    */
   async put(slotName, data, opts) {
+    if (this.objectStore && this.blobFields?.[slotName]?.external) {
+      const policy = this.blobFields[slotName];
+      let contentType = opts?.mimeType;
+      if (!contentType) {
+        const detected = detectMagic(data.subarray(0, 16));
+        contentType = detected?.mime ?? "application/octet-stream";
+      }
+      const key = `${this.collection}/${this.recordId}/${slotName}`;
+      const isPublic = policy.public === true;
+      const backlink = await this.buildBacklink(slotName, policy.backlink ?? "opaque-token");
+      await this.objectStore.putObject(key, data, {
+        contentType,
+        public: isPublic,
+        ...backlink.userMeta ? { userMeta: backlink.userMeta } : {}
+      });
+      const uploaderUserId2 = opts?.uploadedBy ?? this.userId;
+      let oldETag;
+      await this.casUpdateSlots((slots) => {
+        oldETag = slots[slotName]?.eTag || void 0;
+        const prevMeta = slots[slotName]?.external?.meta;
+        slots[slotName] = {
+          eTag: "",
+          external: {
+            key,
+            contentType,
+            ...isPublic ? { public: true } : {},
+            ...backlink.token ? { backlink: backlink.token } : {},
+            ...prevMeta ? { meta: prevMeta } : {}
+          },
+          filename: slotName,
+          size: data.byteLength,
+          mimeType: contentType,
+          uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          ...uploaderUserId2 !== void 0 ? { uploadedBy: uploaderUserId2 } : {}
+        };
+        return slots;
+      });
+      if (oldETag) {
+        await this.releaseRef(oldETag, 1, false).catch(() => {
+        });
+      }
+      return;
+    }
     const blobDEK = this.encrypted ? await this.getDEK(BLOB_COLLECTION) : null;
     const eTag = blobDEK ? await hmacSha256Hex(blobDEK, data) : await plainSha256Hex(data);
     let mimeType = opts?.mimeType;
@@ -888,13 +1140,21 @@ var BlobSet = class {
     } else {
       shouldCompress = true;
     }
+    if (this.debugPlaintext) shouldCompress = false;
     const existingBlob = await this.loadBlobObject(eTag);
     if (existingBlob) {
       await this.casUpdateRefCount(eTag, 1);
     } else {
       const { bytes: compressed, algorithm } = shouldCompress ? await compressBytes(data) : { bytes: data, algorithm: "none" };
-      const chunkSize = this.effectiveChunkSize(opts);
+      const chunkSize = this.debugPlaintext ? Math.max(compressed.byteLength, 1) : this.effectiveChunkSize(opts);
       const chunkCount = Math.max(1, Math.ceil(compressed.byteLength / chunkSize));
+      let chunkKey = blobDEK;
+      let wrappedCek;
+      if (blobDEK && this.erasableBlobs) {
+        const contentCek = await generateDEK();
+        wrappedCek = await wrapCek(contentCek, blobDEK);
+        chunkKey = contentCek;
+      }
       for (let i = 0; i < chunkCount; i++) {
         const start = i * chunkSize;
         await this.writeChunk(
@@ -902,7 +1162,7 @@ var BlobSet = class {
           i,
           chunkCount,
           compressed.subarray(start, start + chunkSize),
-          blobDEK
+          chunkKey
         );
       }
       await this.writeBlobObject({
@@ -914,7 +1174,8 @@ var BlobSet = class {
         chunkCount,
         ...mimeType !== void 0 ? { mimeType } : {},
         createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-        refCount: 1
+        refCount: 1,
+        ...wrappedCek !== void 0 ? { _cek: wrappedCek } : {}
       });
     }
     const uploaderUserId = opts?.uploadedBy ?? this.userId;
@@ -936,7 +1197,7 @@ var BlobSet = class {
     if (this._deferredRefDecrement) {
       const oldETag = this._deferredRefDecrement;
       this._deferredRefDecrement = void 0;
-      await this.casUpdateRefCount(oldETag, -1).catch(() => {
+      await this.releaseRef(oldETag, 1, false).catch(() => {
       });
     }
   }
@@ -950,10 +1211,114 @@ var BlobSet = class {
     const { slots } = await this.loadSlots();
     const slot = slots[slotName];
     if (!slot) return null;
+    if (slot.external) {
+      if (!this.objectStore) {
+        throw new NotFoundError(`Blob slot "${slotName}" is external but no objectStore is configured`);
+      }
+      return this.objectStore.getObject(slot.external.key);
+    }
     const result = await this.loadBlobObject(slot.eTag);
     if (!result) return null;
     return this.fetchAllChunks(result.blob);
   }
+  /**
+   * A URL to fetch an `external` slot's object directly — presigned
+   * (time-limited) or public, per the projection. Returns `null` if the slot
+   * does not exist. Throws for a non-external slot (use `get()`/`response()`).
+   */
+  async url(slotName, opts) {
+    const { slots } = await this.loadSlots();
+    const slot = slots[slotName];
+    if (!slot) return null;
+    if (!slot.external) {
+      throw new NotFoundError(`Blob slot "${slotName}" is not external \u2014 url() is only for external fields`);
+    }
+    if (!this.objectStore) {
+      throw new NotFoundError(`Blob slot "${slotName}" is external but no objectStore is configured`);
+    }
+    return this.objectStore.objectUrl(slot.external.key, opts);
+  }
+  /**
+   * Build the backlink stamped onto an external object's metadata — the
+   * self-describing "secondary store" reference back to this record. See
+   * {@link BlobFieldPolicy.backlink}. Returns the `userMeta` to attach and, for
+   * `opaque-token`, the `token` to record on the slot.
+   */
+  async buildBacklink(slotName, mode) {
+    if (mode === "none") return {};
+    const ref = { vault: this.vault, collection: this.collection, record: this.recordId, field: slotName };
+    if (mode === "plain") {
+      return {
+        userMeta: {
+          "noydb-vault": ref.vault,
+          "noydb-collection": ref.collection,
+          "noydb-record": ref.record,
+          "noydb-field": ref.field
+        }
+      };
+    }
+    if (mode === "encrypted" && this.encrypted) {
+      const dek = await this.getDEK(BLOB_COLLECTION);
+      const { iv, data } = await encrypt(JSON.stringify(ref), dek);
+      return { userMeta: { "noydb-backlink-enc": `${iv}.${data}` } };
+    }
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+    const token = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    return { userMeta: { "noydb-backlink": token }, token };
+  }
+  /**
+   * Adopt an EXISTING object in the projection into this slot **without
+   * re-uploading** — used by import/bootstrap to anchor objects already in the
+   * bucket. Writes the external slot record (the catalog entry).
+   */
+  async adoptExternal(slotName, ref) {
+    const uploaderUserId = this.userId;
+    await this.casUpdateSlots((slots) => {
+      slots[slotName] = {
+        eTag: "",
+        external: {
+          key: ref.key,
+          ...ref.contentType ? { contentType: ref.contentType } : {},
+          ...ref.public ? { public: true } : {},
+          ...ref.backlink ? { backlink: ref.backlink } : {},
+          ...ref.meta ? { meta: ref.meta } : {}
+        },
+        filename: slotName,
+        size: ref.size ?? 0,
+        ...ref.contentType ? { mimeType: ref.contentType } : {},
+        uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        ...uploaderUserId !== void 0 ? { uploadedBy: uploaderUserId } : {}
+      };
+      return slots;
+    });
+  }
+  /**
+   * Merge derived metadata (video `duration`, image `width`/`height`, arbitrary
+   * metatags) into an external slot's secondary metadata store. Typically called
+   * from an AWS-side processing callback (MediaConvert / ffprobe / Rekognition)
+   * once it has probed the object. No-op for a missing or non-external slot.
+   */
+  async setExternalMeta(slotName, meta) {
+    await this.casUpdateSlots((slots) => {
+      const slot = slots[slotName];
+      if (!slot?.external) return null;
+      slots[slotName] = {
+        ...slot,
+        external: { ...slot.external, meta: { ...slot.external.meta, ...meta } }
+      };
+      return slots;
+    });
+  }
+  /**
+   * Read an external slot's synced derived metadata (the secondary store).
+   * Returns `null` for a missing or non-external slot, `{}` if none synced yet.
+   */
+  async externalMeta(slotName) {
+    const { slots } = await this.loadSlots();
+    const slot = slots[slotName];
+    if (!slot?.external) return null;
+    return slot.external.meta ?? {};
+  }
   /**
    * List all slot entries for this record.
    * Returns metadata only — no chunk data is loaded.
@@ -967,15 +1332,22 @@ var BlobSet = class {
    * Decrements refCount on the blob. Chunks are GC'd by `vault.blobGC()`.
    */
   async delete(slotName) {
-    let eTagToDecrement;
+    let eTagToRelease;
+    let externalKeyToDelete;
     await this.casUpdateSlots((slots) => {
       if (!(slotName in slots)) return null;
-      eTagToDecrement = slots[slotName].eTag;
+      const slot = slots[slotName];
+      if (slot.external) externalKeyToDelete = slot.external.key;
+      else eTagToRelease = slot.eTag;
       delete slots[slotName];
       return slots;
     });
-    if (eTagToDecrement) {
-      await this.casUpdateRefCount(eTagToDecrement, -1).catch(() => {
+    if (externalKeyToDelete && this.objectStore) {
+      await this.objectStore.deleteObject(externalKeyToDelete).catch(() => {
+      });
+    }
+    if (eTagToRelease) {
+      await this.releaseRef(eTagToRelease, 1, false).catch(() => {
       });
     }
   }
@@ -1058,7 +1430,7 @@ var BlobSet = class {
     await this.writeVersionRecord(slotName, record);
     await this.casUpdateRefCount(slot.eTag, 1);
     if (existing && existing.eTag !== slot.eTag) {
-      await this.casUpdateRefCount(existing.eTag, -1).catch(() => {
+      await this.releaseRef(existing.eTag, 1, false).catch(() => {
       });
     }
   }
@@ -1101,7 +1473,7 @@ var BlobSet = class {
     const record = await this.loadVersionRecord(slotName, label);
     if (!record) return;
     await this.deleteVersionRecord(slotName, label);
-    await this.casUpdateRefCount(record.eTag, -1).catch(() => {
+    await this.releaseRef(record.eTag, 1, false).catch(() => {
     });
   }
   /**
@@ -1240,6 +1612,91 @@ function withBlobs() {
   };
 }
 
+// src/blobs/object-projection.ts
+function memoryObjectProjection(opts = {}) {
+  const base = opts.baseUrl ?? "memory://objects";
+  const store = /* @__PURE__ */ new Map();
+  return {
+    name: "memory",
+    async putObject(key, bytes, o) {
+      store.set(key, {
+        bytes,
+        contentType: o.contentType,
+        public: o.public === true,
+        ...o.userMeta ? { userMeta: o.userMeta } : {}
+      });
+    },
+    async getObject(key) {
+      return store.get(key)?.bytes ?? null;
+    },
+    async deleteObject(key) {
+      store.delete(key);
+    },
+    async headObject(key) {
+      const e = store.get(key);
+      if (!e) return null;
+      return {
+        size: e.bytes.byteLength,
+        contentType: e.contentType,
+        ...e.userMeta ? { userMeta: e.userMeta } : {}
+      };
+    },
+    async objectUrl(key, o) {
+      const e = store.get(key);
+      if (e?.public) return `${base}/${key}`;
+      return `${base}/${key}?sig=memory&expires=${o?.expiresInSeconds ?? 900}`;
+    },
+    async putUrl(key, o) {
+      return `${base}/${key}?upload=memory&ct=${encodeURIComponent(o.contentType)}`;
+    },
+    async listPrefix(prefix) {
+      const out = [];
+      for (const [key, e] of store) {
+        if (!key.startsWith(prefix)) continue;
+        out.push({
+          key,
+          meta: { size: e.bytes.byteLength, contentType: e.contentType, ...e.userMeta ? { userMeta: e.userMeta } : {} }
+        });
+      }
+      return out;
+    }
+  };
+}
+
+// src/blobs/import-external.ts
+function defaultDeriveRecordId(key) {
+  const parts = key.split("/");
+  return parts.length >= 2 ? parts[parts.length - 2] ?? null : null;
+}
+async function importExternalObjects(args) {
+  const { collection, objectStore, field } = args;
+  const opts = args.options ?? {};
+  const derive = opts.deriveRecordId ?? defaultDeriveRecordId;
+  const makeRecord = opts.makeRecord ?? ((id) => ({ id }));
+  const objects = await objectStore.listPrefix(opts.prefix ?? "");
+  const recordIds = [];
+  let imported = 0;
+  let skipped = 0;
+  for (const { key, meta } of objects) {
+    const recordId = derive(key);
+    if (!recordId) {
+      skipped++;
+      continue;
+    }
+    if (await collection.get(recordId) == null) {
+      await collection.put(recordId, makeRecord(recordId));
+    }
+    await collection.blob(recordId).adoptExternal(field, {
+      key,
+      ...meta.size !== void 0 ? { size: meta.size } : {},
+      ...meta.contentType ? { contentType: meta.contentType } : {}
+    });
+    recordIds.push(recordId);
+    imported++;
+  }
+  return { imported, skipped, recordIds };
+}
+
 // src/blobs/blob-compaction.ts
 init_crypto();
 var BLOB_EVICTION_AUDIT_COLLECTION = "_blob_eviction_audit";
@@ -1252,6 +1709,7 @@ async function runCompaction(ctx, options = {}) {
   let evicted = 0;
   let records = 0;
   let auditEntries = 0;
+  let held = 0;
   let collectionsWithPolicy = 0;
   outer: for (const collectionName of allCollections) {
     if (collectionName.startsWith("_")) continue;
@@ -1275,6 +1733,10 @@ async function runCompaction(ctx, options = {}) {
         if (!policy) continue;
         const reason = evaluatePolicy(policy, record, slot, now);
         if (!reason) continue;
+        if (isHeld(policy, record, now)) {
+          held += 1;
+          continue;
+        }
         if (!dryRun) {
           await ctx.deleteSlot(collectionName, recordId, slot.name);
           await writeAuditEntry(ctx, {
@@ -1299,9 +1761,32 @@ async function runCompaction(ctx, options = {}) {
     records,
     collections: collectionsWithPolicy,
     auditEntries,
+    held,
     byCollection
   };
 }
+function isHeld(policy, record, now) {
+  if (policy.legalHold) {
+    try {
+      if (policy.legalHold(record)) return true;
+    } catch {
+      return true;
+    }
+  }
+  if (policy.retainUntil) {
+    try {
+      const until = policy.retainUntil(record);
+      if (until !== null && until !== void 0) {
+        const t = until instanceof Date ? until.getTime() : typeof until === "number" ? until : Date.parse(String(until));
+        if (!Number.isFinite(t)) return true;
+        if (t > now.getTime()) return true;
+      }
+    } catch {
+      return true;
+    }
+  }
+  return false;
+}
 function evaluatePolicy(policy, record, slot, now) {
   let ttlTriggered = false;
   let predicateTriggered = false;
@@ -1473,7 +1958,9 @@ function generateBatchId() {
   createExportBlobsHandle,
   detectMagic,
   detectMimeType,
+  importExternalObjects,
   isPreCompressed,
+  memoryObjectProjection,
   runCompaction,
   withBlobs
 });