@noy-db/hub 0.4.0-pre.0 → 0.4.0-pre.2

package/dist/{chunk-GULTLPFB.js → chunk-XGVDLQJE.js}

@@ -1,12 +1,12 @@
 import {
   installViaBinder
-} from "./chunk-JVBO4SZL.js";
+} from "./chunk-STR7WBOB.js";
 import {
   LocaleNotSpecifiedError,
   MissingTranslationError,
   ScriptViolationError,
   TranslatorNotConfiguredError
-} from "./chunk-W2OG6JOL.js";
+} from "./chunk-IGM563N5.js";
 
 // src/port/with/i18n-strategy.ts
 function notEnabled(op) {
@@ -618,4 +618,4 @@ export {
   presentI18nForJoin,
   stripI18nFilled
 };
-//# sourceMappingURL=chunk-GULTLPFB.js.map
+//# sourceMappingURL=chunk-XGVDLQJE.js.map

package/dist/{chunk-JFCV5QIK.js → chunk-XULHFSHO.js}

@@ -1,16 +1,16 @@
 import {
   buildAccessibleBundle,
   resolveAccessibleCollections
-} from "./chunk-WKGF2TJR.js";
+} from "./chunk-25ZDB25Z.js";
 import {
   sha256Hex
-} from "./chunk-HOONYZY2.js";
+} from "./chunk-5P5AAXYA.js";
 import {
   NOYDB_FORMAT_VERSION
-} from "./chunk-VCTXU4AT.js";
+} from "./chunk-5BHNQNBI.js";
 import {
   ReadOnlyError
-} from "./chunk-W2OG6JOL.js";
+} from "./chunk-IGM563N5.js";
 
 // src/with-audit/portability/withdraw-accessible.ts
 var FROZEN_SNAPSHOTS_COLLECTION = "_frozen_snapshots";
@@ -114,4 +114,4 @@ export {
   freezeAndDeleteClosure,
   withdrawAccessibleData
 };
-//# sourceMappingURL=chunk-JFCV5QIK.js.map
+//# sourceMappingURL=chunk-XULHFSHO.js.map

package/dist/{chunk-S6Q37VGE.js → chunk-XW7NWO4A.js}

@@ -1,6 +1,6 @@
 import {
   AttestationNotEnabledError
-} from "./chunk-W2OG6JOL.js";
+} from "./chunk-IGM563N5.js";
 
 // src/with-audit/attestation/strategy.ts
 var NO_ATTESTATION = {
@@ -27,4 +27,4 @@ var NO_ATTESTATION = {
 export {
   NO_ATTESTATION
 };
-//# sourceMappingURL=chunk-S6Q37VGE.js.map
+//# sourceMappingURL=chunk-XW7NWO4A.js.map

package/dist/{chunk-YCH5GBN6.js → chunk-Y5E6CH6S.js}

@@ -4,19 +4,19 @@ import {
   grant,
   revoke,
   rotateKeys
-} from "./chunk-554KLAAN.js";
+} from "./chunk-HVZT5T22.js";
 import {
   openEnvelopeJson
-} from "./chunk-W4TCUGQR.js";
+} from "./chunk-PEY6ZTCF.js";
 import {
   encrypt
-} from "./chunk-HOONYZY2.js";
+} from "./chunk-5P5AAXYA.js";
 import {
   NOYDB_FORMAT_VERSION
-} from "./chunk-VCTXU4AT.js";
+} from "./chunk-5BHNQNBI.js";
 import {
   PermissionDeniedError
-} from "./chunk-W2OG6JOL.js";
+} from "./chunk-IGM563N5.js";
 
 // src/with-party/team/active.ts
 function withTeam() {
@@ -96,4 +96,4 @@ export {
   listCredentials,
   credentialStatus
 };
-//# sourceMappingURL=chunk-YCH5GBN6.js.map
+//# sourceMappingURL=chunk-Y5E6CH6S.js.map

package/dist/{chunk-GDG5VVYG.js → chunk-YG2EG6CB.js}

@@ -1,14 +1,14 @@
 import {
   canonicalize,
   derivePersistedSchema
-} from "./chunk-BOKIKJJB.js";
+} from "./chunk-EDC6MLXV.js";
 import {
   loadPersistedSchemaEntry,
   savePersistedSchema
-} from "./chunk-CJ5KKU6X.js";
+} from "./chunk-IGAIOGCN.js";
 import {
   ConflictError
-} from "./chunk-W2OG6JOL.js";
+} from "./chunk-IGM563N5.js";
 
 // src/with-shape/schema-update/delta.ts
 function computeSchemaDelta(stored, fresh, collection) {
@@ -164,4 +164,4 @@ export {
   persistClassifiedMarker,
   persistSatelliteMarker
 };
-//# sourceMappingURL=chunk-GDG5VVYG.js.map
+//# sourceMappingURL=chunk-YG2EG6CB.js.map

package/dist/{chunk-UHNGNKLV.js → chunk-YGBIBOCR.js}

@@ -1,15 +1,15 @@
 import {
   assertTierAccess,
   dekKey
-} from "./chunk-UC2ETWF3.js";
+} from "./chunk-MSO2C3KG.js";
 import {
   liveRecordIsElevated,
   liveRecordTier
-} from "./chunk-DRWBEDYO.js";
+} from "./chunk-NM4LVUXH.js";
 import {
   openEnvelopeJson,
   writeEnvelopeBody
-} from "./chunk-W4TCUGQR.js";
+} from "./chunk-PEY6ZTCF.js";
 import {
   base64ToBuffer,
   bufferToBase64,
@@ -21,19 +21,53 @@ import {
   sha256Hex,
   unwrapCek,
   wrapCek
-} from "./chunk-HOONYZY2.js";
+} from "./chunk-5P5AAXYA.js";
 import {
   NOYDB_FORMAT_VERSION
-} from "./chunk-VCTXU4AT.js";
+} from "./chunk-5BHNQNBI.js";
 import {
   BlobIntentPendingError,
+  BlobOfflineError,
   ConflictError,
   NotFoundError,
   TamperedError,
   TierNotGrantedError,
   UnsupportedTierCompositionError,
   ValidationError
-} from "./chunk-W2OG6JOL.js";
+} from "./chunk-IGM563N5.js";
+
+// src/with-shape/blobs/blob-pinning.ts
+function memoryBlobPinStore() {
+  const rows = /* @__PURE__ */ new Map();
+  return {
+    async get(key) {
+      return rows.get(key) ?? null;
+    },
+    async set(key, entry) {
+      rows.set(key, entry);
+    },
+    async delete(key) {
+      rows.delete(key);
+    },
+    async entries(prefix) {
+      const out = [];
+      for (const [key, entry] of rows) {
+        if (key.startsWith(prefix)) out.push({ key, entry });
+      }
+      return out;
+    }
+  };
+}
+function createBlobPinCache(store) {
+  return {
+    store: store ?? memoryBlobPinStore(),
+    stats: { hits: 0, misses: 0, bytesDownloaded: 0 }
+  };
+}
+function blobPinKey(vault, collection, recordId, slotName) {
+  const prefix = `${vault}::${collection}::${recordId}::`;
+  return slotName === void 0 ? prefix : prefix + slotName;
+}
 
 // src/with-shape/blobs/mime-magic.ts
 function hex(s) {
@@ -403,6 +437,12 @@ var BlobSet = class _BlobSet {
   objectStore;
   blobFields;
   keyring;
+  /**
+   * Device-local pin registry + external side-cache + KPI counters (#808).
+   * Injected by `withBlobs()` (one shared instance per strategy — per
+   * "device"); absent on a direct construction that never threads one.
+   */
+  pinCache;
   /**
    * Set only on the cleared clone `atTier()` returns (#749) — never by
    * `openSlot`/`Collection.blob()`. Its presence is what makes a `BlobSet`
@@ -425,6 +465,7 @@ var BlobSet = class _BlobSet {
     this.blobFields = opts.blobFields;
     this.keyring = opts.keyring;
     this.clearedTier = opts.clearedTier;
+    this.pinCache = opts.pinCache;
   }
   /**
    * #724 I1 completion: a legacy (non-`perRecordKeys`) blob has no per-blob
@@ -582,7 +623,8 @@ var BlobSet = class _BlobSet {
       ...this.userId !== void 0 ? { userId: this.userId } : {},
       ...this.maxBlobBytes !== void 0 ? { maxBlobBytes: this.maxBlobBytes } : {},
       ...this.objectStore !== void 0 ? { objectStore: this.objectStore } : {},
-      ...this.blobFields !== void 0 ? { blobFields: this.blobFields } : {}
+      ...this.blobFields !== void 0 ? { blobFields: this.blobFields } : {},
+      ...this.pinCache !== void 0 ? { pinCache: this.pinCache } : {}
     });
   }
   /** The internal collection that holds slot metadata for this collection's blobs. */
@@ -1115,6 +1157,13 @@ var BlobSet = class _BlobSet {
    * which are fixed for the operation's lifetime in the marker (C1/C2).
    */
   async shredAllForRecord(ownerTier) {
+    if (this.pinCache) {
+      try {
+        const rows = await this.pinCache.store.entries(blobPinKey(this.vault, this.collection, this.recordId));
+        for (const { key } of rows) await this.pinCache.store.delete(key);
+      } catch {
+      }
+    }
     const tierArg = ownerTier ?? 0;
     const intent = await this.resolveShredIntent(tierArg);
     if (!intent) return this.unmarkedShred(tierArg);
@@ -1988,8 +2037,11 @@ var BlobSet = class _BlobSet {
     for (let i = 0; i < blob.chunkCount; i++) {
       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}"`
+        throw new BlobOfflineError(
+          this.collection,
+          this.recordId,
+          void 0,
+          `chunk ${i}/${blob.chunkCount} for eTag "${blob.eTag}" is absent from the local store \u2014 content not yet synced to this device, or evicted (#808)`
         );
       }
       chunks.push(chunk);
@@ -2310,7 +2362,11 @@ var BlobSet = class _BlobSet {
   /**
    * Fetch all bytes for the named slot.
    * Returns `null` if the slot does not exist.
-   * Throws `NotFoundError` if the index entry exists but a chunk is missing.
+   * Throws `BlobOfflineError` if the content is not available locally (#808):
+   * an internal blob whose chunk envelopes are absent from the local store, or
+   * an external slot with no local cached copy while the object store is
+   * unreachable. External reads populate the device-local encrypted
+   * side-cache, so a repeat read is served locally (see `pin()`).
    */
   async get(slotName) {
     if (await this.ownerRecordElevated()) return null;
@@ -2318,15 +2374,14 @@ var BlobSet = class _BlobSet {
     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);
+      return this.readExternal(slotName, slot);
     }
     const result = await this.loadBlobObject(slot.eTag);
     if (!result) return null;
     const blobDEK = this.encrypted ? await this.getDEK(dekKey(BLOB_COLLECTION, result.atTier)) : void 0;
-    return this.fetchAllChunks(result.blob, blobDEK, this.flatFallbackVerifyETag(slot.eTag, result.atTier));
+    const bytes = await this.fetchAllChunks(result.blob, blobDEK, this.flatFallbackVerifyETag(slot.eTag, result.atTier));
+    await this.recordLocalHit(slotName);
+    return bytes;
   }
   /**
    * A URL to fetch an `external` slot's object directly — presigned
@@ -2437,15 +2492,35 @@ var BlobSet = class _BlobSet {
   /**
    * List all slot entries for this record.
    * Returns metadata only — no chunk data is loaded.
+   *
+   * #808: when a pin registry is present (`withBlobs()`), each entry is
+   * annotated with this DEVICE's view — `pinned` / `lastAccessAt` /
+   * `cachedBytes` (see their `SlotInfo` doc comments). The annotations come
+   * from the device-local registry, never the vault store, and are what
+   * `vault.compact()`'s pin exemption + cache-budget LRU pass key off.
    */
   async list() {
     if (await this.ownerRecordElevated()) return [];
     const { slots } = await this.loadSlots();
-    return Object.entries(slots).map(([name, slot]) => {
+    const infos = Object.entries(slots).map(([name, slot]) => {
       const pub = { ...slot };
       delete pub.pendingRelease;
       return { name, ...pub };
     });
+    if (!this.pinCache) return infos;
+    const prefix = blobPinKey(this.vault, this.collection, this.recordId);
+    const rows = await this.pinCache.store.entries(prefix);
+    const byName = new Map(rows.map(({ key, entry }) => [key.slice(prefix.length), entry]));
+    return infos.map((info) => {
+      const entry = byName.get(info.name);
+      if (!entry) return info;
+      return {
+        ...info,
+        ...entry.pinned ? { pinned: true } : {},
+        ...entry.lastAccessAt !== void 0 ? { lastAccessAt: entry.lastAccessAt } : {},
+        ...entry.cachedBytes !== void 0 ? { cachedBytes: entry.cachedBytes } : {}
+      };
+    });
   }
   /**
    * Delete the named slot from this record.
@@ -2471,6 +2546,218 @@ var BlobSet = class _BlobSet {
       await this.releaseRef(eTagToRelease, 1, false).catch(() => {
       });
     }
+    if (this.pinCache) {
+      await this.pinCache.store.delete(this.pinKeyFor(slotName)).catch(() => {
+      });
+    }
+  }
+  // ─── Public API: Offline pinning + device-local cache (#808) ──────
+  /**
+   * Pin the named slot for offline availability ON THIS DEVICE.
+   *
+   * - Downloads eagerly (call while online): an internal blob's chunks are
+   *   fetched once to prove they are locally readable; an `external` slot's
+   *   bytes are fetched from the object store and kept in the device-local
+   *   side-cache, **encrypted** under the vault's `_blob` DEK via the same
+   *   enclave path as chunk encryption (the object-store copy sits outside
+   *   the ZK envelope by design; the local copy does not).
+   * - A pinned slot is EXEMPT from `vault.compact()` eviction — both the
+   *   `blobFields` policy pass and the `cacheBudget` LRU pass.
+   * - Pin state is device-local (never synced): it lives in the `withBlobs()`
+   *   pin registry, not in the vault store. Each device pins for itself.
+   *
+   * Throws `NotFoundError` for a missing slot and `BlobOfflineError` when the
+   * eager download cannot complete (offline).
+   */
+  async pin(slotName) {
+    this.assertKeyPartSafe(this.recordId, "record id");
+    this.assertKeyPartSafe(slotName, "slot name");
+    const pc = this.requirePinCache("pin");
+    if (await this.ownerRecordElevated()) {
+      throw new NotFoundError(`Slot "${slotName}" not found on record "${this.recordId}"`);
+    }
+    const { slots } = await this.loadSlots();
+    const slot = slots[slotName];
+    if (!slot) throw new NotFoundError(`Slot "${slotName}" not found on record "${this.recordId}"`);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (slot.external) {
+      const bytes = await this.readExternal(slotName, slot);
+      if (bytes === null) {
+        throw new NotFoundError(`External object for blob slot "${slotName}" is missing from the object store`);
+      }
+      const key2 = this.pinKeyFor(slotName);
+      const entry = await pc.store.get(key2);
+      if (entry?.cipher) {
+        await pc.store.set(key2, { ...entry, pinned: true, pinnedAt: entry.pinnedAt ?? now });
+      } else {
+        await this.cacheExternalCopy(slotName, bytes, { pin: true });
+      }
+      return;
+    }
+    const result = await this.loadBlobObject(slot.eTag);
+    if (!result) throw new NotFoundError(`BlobObject ${slot.eTag} not found`);
+    const blobDEK = this.encrypted ? await this.getDEK(dekKey(BLOB_COLLECTION, result.atTier)) : void 0;
+    await this.fetchAllChunks(result.blob, blobDEK, this.flatFallbackVerifyETag(slot.eTag, result.atTier));
+    const key = this.pinKeyFor(slotName);
+    const prev = await pc.store.get(key);
+    await pc.store.set(key, { ...prev ?? {}, pinned: true, pinnedAt: now, lastAccessAt: now });
+  }
+  /**
+   * Unpin the named slot on this device — it returns to the normal lifecycle:
+   * `blobFields` policy eviction applies again, and any local cached copy
+   * (external slots) stays but becomes budget-managed (`cacheBudget` LRU).
+   * A no-op when the slot is not pinned here.
+   */
+  async unpin(slotName) {
+    this.assertKeyPartSafe(slotName, "slot name");
+    const pc = this.requirePinCache("unpin");
+    const key = this.pinKeyFor(slotName);
+    const entry = await pc.store.get(key);
+    if (!entry?.pinned) return;
+    const rest = { ...entry, pinned: false };
+    delete rest.pinnedAt;
+    await pc.store.set(key, rest);
+  }
+  /** Whether the named slot is pinned for offline ON THIS DEVICE (#808). */
+  async isPinned(slotName) {
+    const pc = this.requirePinCache("isPinned");
+    const entry = await pc.store.get(this.pinKeyFor(slotName));
+    return entry?.pinned === true;
+  }
+  /**
+   * Drop this slot's device-local cached copy (the encrypted external
+   * side-cache) WITHOUT touching the slot, the vault store, or the object
+   * store. Returns the plaintext bytes freed (0 when nothing was cached, the
+   * slot is pinned — pinned copies are exempt — or no registry is present).
+   * The cache-budget pass inside `vault.compact()` is the expected caller;
+   * the LRU access row itself is kept.
+   */
+  async dropLocalCache(slotName) {
+    const pc = this.pinCache;
+    if (!pc) return 0;
+    const key = this.pinKeyFor(slotName);
+    const entry = await pc.store.get(key);
+    if (!entry || entry.pinned || !entry.cipher) return 0;
+    const freed = entry.cachedBytes ?? 0;
+    const rest = { ...entry };
+    delete rest.cipher;
+    delete rest.cachedBytes;
+    await pc.store.set(key, rest);
+    return freed;
+  }
+  // ─── Internal: device-local pin registry plumbing (#808) ──────────
+  /** This slot's registry key — see {@link blobPinKey}. */
+  pinKeyFor(slotName) {
+    return blobPinKey(this.vault, this.collection, this.recordId, slotName);
+  }
+  /** AAD binding for a cached external copy: the row's own registry key. */
+  pinCopyAAD(slotName) {
+    return new TextEncoder().encode(`pin:${this.pinKeyFor(slotName)}`);
+  }
+  requirePinCache(op) {
+    if (!this.pinCache) {
+      throw new ValidationError(
+        `BlobSet.${op}() requires the withBlobs() pin registry \u2014 this handle was constructed without one (#808)`
+      );
+    }
+    return this.pinCache;
+  }
+  /** KPI hit + LRU access stamp for a successful LOCAL read. No-op without a registry. */
+  async recordLocalHit(slotName, prev) {
+    const pc = this.pinCache;
+    if (!pc) return;
+    pc.stats.hits += 1;
+    const key = this.pinKeyFor(slotName);
+    const entry = prev ?? await pc.store.get(key);
+    await pc.store.set(key, { ...entry ?? { pinned: false }, lastAccessAt: (/* @__PURE__ */ new Date()).toISOString() });
+  }
+  /**
+   * Read an `external` slot (#808 taxonomy): local encrypted side-cache first
+   * (hit); else the object store (miss + `bytesDownloaded`), auto-caching the
+   * fetched bytes so the NEXT read — and any later offline read — is local.
+   * A network failure with no local copy is the typed `BlobOfflineError`;
+   * a genuinely absent object (fetch succeeded, nothing there) stays `null`.
+   */
+  async readExternal(slotName, slot) {
+    const pc = this.pinCache;
+    if (pc) {
+      const key = this.pinKeyFor(slotName);
+      const entry = await pc.store.get(key);
+      const cached = entry?.cipher ? await this.decryptCachedCopy(slotName, entry.cipher) : null;
+      if (cached) {
+        await this.recordLocalHit(slotName, entry);
+        return cached;
+      }
+    }
+    if (!this.objectStore) {
+      throw new NotFoundError(`Blob slot "${slotName}" is external but no objectStore is configured`);
+    }
+    let bytes;
+    try {
+      bytes = await this.objectStore.getObject(slot.external.key);
+    } catch (err) {
+      throw new BlobOfflineError(
+        this.collection,
+        this.recordId,
+        slotName,
+        "no local cached copy and the object store is unreachable \u2014 pin() the slot while online to keep it readable offline (#808)",
+        err
+      );
+    }
+    if (bytes === null) return null;
+    if (pc) {
+      pc.stats.misses += 1;
+      pc.stats.bytesDownloaded += bytes.byteLength;
+      await this.cacheExternalCopy(slotName, bytes).catch(() => {
+      });
+    }
+    return bytes;
+  }
+  /**
+   * Decrypt a cached external copy. `null` (treated as a cache miss → network
+   * refresh) when the vault keys can no longer open it — e.g. the copy was
+   * cached before the owning record moved tiers, so it is sealed under a DEK
+   * this handle no longer resolves. Genuine non-crypto failures propagate.
+   */
+  async decryptCachedCopy(slotName, cipher) {
+    if (!this.encrypted) return base64ToBuffer(cipher.data);
+    const dek = await this.getDEK(dekKey(BLOB_COLLECTION, await this.ownerTier()));
+    try {
+      return await decryptBytesWithAAD(cipher.iv, cipher.data, dek, this.pinCopyAAD(slotName));
+    } catch (err) {
+      if (err instanceof TamperedError) return null;
+      throw err;
+    }
+  }
+  /**
+   * Write an external slot's bytes into the device-local side-cache —
+   * ENCRYPTED under the vault's `_blob` DEK (owner tier) via the enclave's
+   * AAD-bound path, mirroring chunk encryption; base64 plaintext with
+   * `iv: ''` only on an unencrypted vault (the envelope convention). A
+   * pre-existing pin flag survives the rewrite.
+   */
+  async cacheExternalCopy(slotName, bytes, opts) {
+    const pc = this.pinCache;
+    if (!pc) return;
+    let cipher;
+    if (this.encrypted) {
+      const dek = await this.getDEK(dekKey(BLOB_COLLECTION, await this.ownerTier()));
+      const enc = await encryptBytesWithAAD(bytes, dek, this.pinCopyAAD(slotName));
+      cipher = { iv: enc.iv, data: enc.data };
+    } else {
+      cipher = { iv: "", data: bufferToBase64(bytes) };
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const key = this.pinKeyFor(slotName);
+    const prev = await pc.store.get(key);
+    const pinned = opts?.pin === true || prev?.pinned === true;
+    await pc.store.set(key, {
+      pinned,
+      ...pinned ? { pinnedAt: (opts?.pin === true ? now : prev?.pinnedAt) ?? now } : {},
+      lastAccessAt: now,
+      cachedBytes: bytes.byteLength,
+      cipher
+    });
   }
   /**
    * Return a native `Response` whose body streams the decrypted,
@@ -2763,6 +3050,9 @@ async function plainSha256Hex(data) {
 }
 
 export {
+  memoryBlobPinStore,
+  createBlobPinCache,
+  blobPinKey,
   detectMimeType,
   detectMagic,
   isPreCompressed,
@@ -2779,4 +3069,4 @@ export {
   DEFAULT_CHUNK_SIZE,
   BlobSet
 };
-//# sourceMappingURL=chunk-UHNGNKLV.js.map
+//# sourceMappingURL=chunk-YGBIBOCR.js.map