@qvac/registry-client 0.6.0 → 0.7.0

package/README.md

@@ -26,7 +26,7 @@ Ensure the registry core key is available via environment variables or provided
 'use strict'
 const { QVACRegistryClient } = require('@qvac/registry-client')
 
-async function main () {
+async function main() {
   const client = new QVACRegistryClient({
     registryCoreKey: process.env.QVAC_REGISTRY_CORE_KEY
   })
@@ -120,16 +120,19 @@ result.artifact.stream.pipe(fs.createWriteStream('./model.ggml'))
 This method only waits for the network layer (Corestore + Hyperswarm) — it does not wait for the metadata core to sync, making it faster for known blob coordinates.
 
 ```javascript
-const result = await client.downloadBlob({
-  coreKey: 'ey46cahego89xox118uhyryakz47bcs8bbxu97tnnpmuwmgi5wmo',
-  blockOffset: 0,
-  blockLength: 665,
-  byteOffset: 0,
-  byteLength: 43537433
-}, {
-  outputFile: './downloaded/ggml-tiny-q8_0.bin',
-  timeout: 60000
-})
+const result = await client.downloadBlob(
+  {
+    coreKey: 'ey46cahego89xox118uhyryakz47bcs8bbxu97tnnpmuwmgi5wmo',
+    blockOffset: 0,
+    blockLength: 665,
+    byteOffset: 0,
+    byteLength: 43537433
+  },
+  {
+    outputFile: './downloaded/ggml-tiny-q8_0.bin',
+    timeout: 60000
+  }
+)
 console.log('Downloaded to:', result.artifact.path)
 ```
 
@@ -332,11 +335,11 @@ The client uses custom error codes in the range 19001-20000. All errors extend `
 
 ### Error Codes
 
-| Code | Name | Description | When Thrown |
-|------|------|-------------|-------------|
-| 19001 | FAILED_TO_CONNECT | Connection to registry failed | Missing core key, network issues during initialization |
-| 19002 | FAILED_TO_CLOSE | Failed to close registry cleanly | Resource cleanup errors during shutdown |
-| 19003 | MODEL_NOT_FOUND | Model not found or invalid | Model doesn't exist or missing blob binding |
+| Code  | Name              | Description                      | When Thrown                                            |
+| ----- | ----------------- | -------------------------------- | ------------------------------------------------------ |
+| 19001 | FAILED_TO_CONNECT | Connection to registry failed    | Missing core key, network issues during initialization |
+| 19002 | FAILED_TO_CLOSE   | Failed to close registry cleanly | Resource cleanup errors during shutdown                |
+| 19003 | MODEL_NOT_FOUND   | Model not found or invalid       | Model doesn't exist or missing blob binding            |
 
 ### Error Handling Example
 
@@ -344,7 +347,7 @@ The client uses custom error codes in the range 19001-20000. All errors extend `
 const { QVACRegistryClient } = require('@qvac/registry-client')
 const { QvacErrorRegistryClient } = require('@qvac/registry-client/utils/error')
 
-async function handleErrors () {
+async function handleErrors() {
   const client = new QVACRegistryClient({
     registryCoreKey: process.env.QVAC_REGISTRY_CORE_KEY
   })

package/bin/cli.js

@@ -11,7 +11,7 @@ const VERSION = require('../package.json').version
 
 // --- Helpers ---
 
-function createClient (parentFlags) {
+function createClient(parentFlags) {
   const opts = {}
   if (parentFlags.key) opts.registryCoreKey = parentFlags.key
   if (parentFlags.storage) opts.storage = parentFlags.storage
@@ -23,13 +23,13 @@ function createClient (parentFlags) {
   return new QVACRegistryClient(opts)
 }
 
-function getRootFlags (cmd) {
+function getRootFlags(cmd) {
   let current = cmd.command || cmd
   while (current.parent) current = current.parent
   return current.flags || {}
 }
 
-function formatSize (bytes) {
+function formatSize(bytes) {
   if (!bytes) return 'N/A'
   if (bytes >= 1024 * 1024 * 1024) return (bytes / (1024 * 1024 * 1024)).toFixed(2) + ' GB'
   if (bytes >= 1024 * 1024) return (bytes / (1024 * 1024)).toFixed(2) + ' MB'
@@ -37,14 +37,14 @@ function formatSize (bytes) {
   return bytes + ' B'
 }
 
-function printModelCompact (model) {
+function printModelCompact(model) {
   const parts = [model.path, model.source]
   if (model.quantization) parts.push(model.quantization)
   if (model.params) parts.push(model.params)
   console.log(parts.join('\t'))
 }
 
-function printModelFull (model, opts = {}) {
+function printModelFull(model, opts = {}) {
   const blob = model.blobBinding || {}
   const coreKey = blob.coreKey ? IdEnc.normalize(blob.coreKey) : 'N/A'
 
@@ -55,7 +55,9 @@ function printModelFull (model, opts = {}) {
   if (model.quantization) console.log(`    quantization: ${model.quantization}`)
   if (model.params) console.log(`    params:       ${model.params}`)
   console.log(`    size:         ${formatSize(blob.byteLength || model.sizeBytes)}`)
-  if (model.licenseId || model.license) console.log(`    license:      ${model.licenseId || model.license}`)
+  if (model.licenseId || model.license) {
+    console.log(`    license:      ${model.licenseId || model.license}`)
+  }
   if (blob.sha256 || model.sha256) console.log(`    sha256:       ${blob.sha256 || model.sha256}`)
   if (opts.verbose && model.description) console.log(`    description:  ${model.description}`)
   if (opts.verbose) console.log(`    blob core:    ${coreKey}`)
@@ -63,7 +65,7 @@ function printModelFull (model, opts = {}) {
   console.log()
 }
 
-async function withClient (cmd, fn) {
+async function withClient(cmd, fn) {
   const rootFlags = getRootFlags(cmd)
   const client = createClient(rootFlags)
   try {
@@ -75,7 +77,8 @@ async function withClient (cmd, fn) {
 
 // --- Commands ---
 
-const listCmd = command('list',
+const listCmd = command(
+  'list',
   summary('List models from the registry'),
   description('List all models or filter by name, engine, or quantization.'),
   flag('--name|-n [name]', 'Filter by model name (partial match)'),
@@ -103,10 +106,13 @@ const listCmd = command('list',
       }
 
       if (flags.json) {
-        const out = models.map(m => ({
+        const out = models.map((m) => ({
           ...m,
           blobBinding: m.blobBinding
-            ? { ...m.blobBinding, coreKey: m.blobBinding.coreKey ? IdEnc.normalize(m.blobBinding.coreKey) : undefined }
+            ? {
+                ...m.blobBinding,
+                coreKey: m.blobBinding.coreKey ? IdEnc.normalize(m.blobBinding.coreKey) : undefined
+              }
             : undefined
         }))
         console.log(JSON.stringify(out, null, 2))
@@ -129,7 +135,8 @@ const listCmd = command('list',
   }
 )
 
-const getCmd = command('get',
+const getCmd = command(
+  'get',
   summary('Get a specific model by path and source'),
   arg('<path>', 'Model path (e.g. hf/org/repo/file.gguf)'),
   arg('<source>', 'Model source (e.g. hf, s3)'),
@@ -149,7 +156,12 @@ const getCmd = command('get',
         const out = {
           ...model,
           blobBinding: model.blobBinding
-            ? { ...model.blobBinding, coreKey: model.blobBinding.coreKey ? IdEnc.normalize(model.blobBinding.coreKey) : undefined }
+            ? {
+                ...model.blobBinding,
+                coreKey: model.blobBinding.coreKey
+                  ? IdEnc.normalize(model.blobBinding.coreKey)
+                  : undefined
+              }
             : undefined
         }
         console.log(JSON.stringify(out, null, 2))
@@ -161,7 +173,8 @@ const getCmd = command('get',
   }
 )
 
-const downloadCmd = command('download',
+const downloadCmd = command(
+  'download',
   summary('Download a model from the registry'),
   arg('<path>', 'Model path'),
   arg('<source>', 'Model source (e.g. hf, s3)'),
@@ -192,9 +205,12 @@ const downloadCmd = command('download',
   }
 )
 
-const profileCmd = command('profile',
+const profileCmd = command(
+  'profile',
   summary('Profile download performance for a model'),
-  description('Downloads a model to a temp directory while collecting UDX network stats, connection info, and hypercore metrics. Similar to hyperdrive-profiler but for registry blobs.'),
+  description(
+    'Downloads a model to a temp directory while collecting UDX network stats, connection info, and hypercore metrics. Similar to hyperdrive-profiler but for registry blobs.'
+  ),
   arg('<path>', 'Model path'),
   arg('[source]', 'Model source filter (e.g. hf, s3)'),
   flag('--interval|-i [seconds]', 'Stats print interval in seconds (default: 5)'),
@@ -232,7 +248,8 @@ const profileCmd = command('profile',
 
 // --- Root command ---
 
-const cmd = command('qvac-registry',
+const cmd = command(
+  'qvac-registry',
   header(`qvac-registry v${VERSION}`),
   summary('QVAC Model Registry CLI'),
   footer('Set QVAC_REGISTRY_CORE_KEY env var or use --key to specify the registry core key.'),

package/index.d.ts

@@ -10,6 +10,7 @@ export interface QVACBlobBinding {
   blockLength: number
   byteOffset: number
   byteLength: number
+  sha256: string
 }
 
 export interface QVACModelEntry {
@@ -26,6 +27,29 @@ export interface QVACModelEntry {
   notes?: string
   tags?: string[]
   blobBinding: QVACBlobBinding
+  /**
+   * Raw GGUF key-value metadata extracted at ingest, serialised as a JSON string.
+   *
+   * - Only present for GGUF artifacts; absent for other formats and when
+   *   extraction failed (e.g. some GGUF v3 files).
+   * - Tensor infos are discarded and every `tokenizer.*` key is stripped.
+   * - For sharded models only the first shard (`-00001-of-`) is described.
+   * - Numeric values that exceeded the safe integer range are stringified.
+   */
+  ggufMetadata?: string
+  /**
+   * Points at a weightless description of this artifact: the tensor list an
+   * engine's dry-run fitter reads, with none of the weights.
+   *
+   * - For a GGUF it is a short GGUF holding the tensor list and the settings
+   *   without the tokenizer tables; for a safetensors it is the JSON header.
+   * - Present for GGUF and safetensors artifacts, every shard of a split model
+   *   included; absent for other formats and when it could not be built.
+   * - Written to the writer's active blob core, which is not always the one
+   *   holding the weights; `downloadBlob` takes the binding directly.
+   * - `sha256` covers the description, not the artifact it came from.
+   */
+  fitBlobBinding?: QVACBlobBinding
 }
 
 export interface QVACDownloadedArtifactStream {
@@ -48,7 +72,12 @@ export interface QVACDownloadOptions {
   peerTimeout?: number
   maxRetries?: number
   outputFile?: string
-  onProgress?: (progress: { downloaded: number, total: number, cachedBlocks: number, totalBlocks: number }) => void
+  onProgress?: (progress: {
+    downloaded: number
+    total: number
+    cachedBlocks: number
+    totalBlocks: number
+  }) => void
   signal?: AbortSignal
 }
 
@@ -56,7 +85,12 @@ export interface QVACBlobDownloadOptions {
   timeout?: number
   maxRetries?: number
   outputFile?: string
-  onProgress?: (progress: { downloaded: number, total: number, cachedBlocks: number, totalBlocks: number }) => void
+  onProgress?: (progress: {
+    downloaded: number
+    total: number
+    cachedBlocks: number
+    totalBlocks: number
+  }) => void
   signal?: AbortSignal
 }
 
@@ -91,35 +125,42 @@ export interface FindByParams {
 
 export interface LifecycleSwarmHandle {
   readonly suspended: boolean
-  suspend (opts?: LifecycleLogOptions): Promise<void>
-  resume (opts?: LifecycleLogOptions): Promise<void>
+  suspend(opts?: LifecycleLogOptions): Promise<void>
+  resume(opts?: LifecycleLogOptions): Promise<void>
 }
 
 export interface LifecycleStoreHandle {
-  suspend (opts?: LifecycleLogOptions): Promise<void>
-  resume (): Promise<void>
+  suspend(opts?: LifecycleLogOptions): Promise<void>
+  resume(): Promise<void>
 }
 
 export class QVACRegistryClient extends ReadyResource {
-  constructor (opts?: QVACRegistryClientOptions)
+  constructor(opts?: QVACRegistryClientOptions)
 
   /** Valid only while the client remains open. Cached handles become stale after close(). */
   readonly corestore: LifecycleStoreHandle | null
   /** Valid only while the client remains open. Cached handles become stale after close(). */
   readonly hyperswarm: LifecycleSwarmHandle | null
 
-  ready (): Promise<void>
-  close (): Promise<void>
-  suspend (opts?: LifecycleLogOptions): Promise<void>
-  resume (opts?: LifecycleLogOptions): Promise<void>
-
-  getModel (path: string, source: string): Promise<QVACModelEntry | null>
-  downloadModel (path: string, source: string, options?: QVACDownloadOptions): Promise<QVACDownloadResult>
-  downloadBlob (blobBinding: QVACBlobBinding, options?: QVACBlobDownloadOptions): Promise<QVACBlobDownloadResult>
-
-  findBy (params?: FindByParams): Promise<QVACModelEntry[]>
-  findModels (query?: QVACModelQuery): Promise<QVACModelEntry[]>
-  findModelsByEngine (query?: QVACModelQuery): Promise<QVACModelEntry[]>
-  findModelsByName (query?: QVACModelQuery): Promise<QVACModelEntry[]>
-  findModelsByQuantization (query?: QVACModelQuery): Promise<QVACModelEntry[]>
+  ready(): Promise<void>
+  close(): Promise<void>
+  suspend(opts?: LifecycleLogOptions): Promise<void>
+  resume(opts?: LifecycleLogOptions): Promise<void>
+
+  getModel(path: string, source: string): Promise<QVACModelEntry | null>
+  downloadModel(
+    path: string,
+    source: string,
+    options?: QVACDownloadOptions
+  ): Promise<QVACDownloadResult>
+  downloadBlob(
+    blobBinding: QVACBlobBinding,
+    options?: QVACBlobDownloadOptions
+  ): Promise<QVACBlobDownloadResult>
+
+  findBy(params?: FindByParams): Promise<QVACModelEntry[]>
+  findModels(query?: QVACModelQuery): Promise<QVACModelEntry[]>
+  findModelsByEngine(query?: QVACModelQuery): Promise<QVACModelEntry[]>
+  findModelsByName(query?: QVACModelQuery): Promise<QVACModelEntry[]>
+  findModelsByQuantization(query?: QVACModelQuery): Promise<QVACModelEntry[]>
 }

package/lib/client.js

@@ -15,9 +15,17 @@ const fs = require('#fs')
 
 const DEFAULT_DOWNLOAD_MAX_RETRIES = 3
 const RETRIABLE_DOWNLOAD_CODES = ['REQUEST_TIMEOUT']
+const INFLIGHT_DRAIN_TIMEOUT_MS = 5000
+const INFLIGHT_DRAIN_POLL_MS = 10
+
+// While the app is backgrounded the swarm is suspended; a retry must wait for
+// resume rather than burn its (small) retry budget timing out against a dead
+// swarm. Bounded so a never-resumed runtime still fails instead of hanging.
+const RESUME_WAIT_MAX_MS = 5 * 60 * 1000
+const RESUME_WAIT_POLL_MS = 200
 
 class QVACRegistryClient extends ReadyResource {
-  constructor (opts = {}) {
+  constructor(opts = {}) {
     super()
 
     this.logger = new Logger(opts.logger)
@@ -40,7 +48,7 @@ class QVACRegistryClient extends ReadyResource {
     this.ready()
   }
 
-  async _open () {
+  async _open() {
     this.logger.debug('_open called')
 
     this.logger.debug('Opening corestore')
@@ -59,10 +67,13 @@ class QVACRegistryClient extends ReadyResource {
     await this._metadataReady
   }
 
-  async _connectMetadataCore () {
+  async _connectMetadataCore() {
     if (!this.registryCoreKey) {
       this.logger.error('Missing registry core key for read mode')
-      throw new QvacErrorRegistryClient({ code: ERR_CODES.FAILED_TO_CONNECT, adds: 'Missing registry core key. Set QVAC_REGISTRY_CORE_KEY environment variable.' })
+      throw new QvacErrorRegistryClient({
+        code: ERR_CODES.FAILED_TO_CONNECT,
+        adds: 'Missing registry core key. Set QVAC_REGISTRY_CORE_KEY environment variable.'
+      })
     }
 
     const viewKey = IdEnc.decode(this.registryCoreKey)
@@ -90,15 +101,18 @@ class QVACRegistryClient extends ReadyResource {
     })
   }
 
-  async _ensureMetadata () {
+  async _ensureMetadata() {
     await this.ready()
     await this._metadataReady
     if (!this.db) {
-      throw new QvacErrorRegistryClient({ code: ERR_CODES.FAILED_TO_CONNECT, adds: 'Registry database not available.' })
+      throw new QvacErrorRegistryClient({
+        code: ERR_CODES.FAILED_TO_CONNECT,
+        adds: 'Registry database not available.'
+      })
     }
   }
 
-  async getModel (path, source) {
+  async getModel(path, source) {
     this._validateString(path, 'path')
     this._validateString(source, 'source')
 
@@ -115,7 +129,7 @@ class QVACRegistryClient extends ReadyResource {
     }
   }
 
-  async findModels (query = {}, opts = {}) {
+  async findModels(query = {}, opts = {}) {
     await this._ensureMetadata()
     const { includeDeprecated = false } = opts
     this.logger.debug('findModels called', { query, includeDeprecated })
@@ -123,25 +137,25 @@ class QVACRegistryClient extends ReadyResource {
     let models = await this.db.findModelsByPath(query).toArray()
 
     if (!includeDeprecated) {
-      models = models.filter(m => !m.deprecated)
+      models = models.filter((m) => !m.deprecated)
     }
 
     return models
   }
 
-  async findModelsByEngine (query = {}) {
+  async findModelsByEngine(query = {}) {
     await this._ensureMetadata()
     this.logger.debug('findModelsByEngine called', { query })
     return this.db.findModelsByEngine(query).toArray()
   }
 
-  async findModelsByName (query = {}) {
+  async findModelsByName(query = {}) {
     await this._ensureMetadata()
     this.logger.debug('findModelsByName called', { query })
     return this.db.findModelsByName(query).toArray()
   }
 
-  async findModelsByQuantization (query = {}) {
+  async findModelsByQuantization(query = {}) {
     await this._ensureMetadata()
     this.logger.debug('findModelsByQuantization called', { query })
     return this.db.findModelsByQuantization(query).toArray()
@@ -157,19 +171,19 @@ class QVACRegistryClient extends ReadyResource {
    * @param {boolean} [params.includeDeprecated=false] - Include deprecated models
    * @returns {Promise<Array>} Array of matching models
    */
-  async findBy (params = {}) {
+  async findBy(params = {}) {
     await this._ensureMetadata()
     this.logger.debug('findBy called', { params })
     return this.db.findBy(params)
   }
 
-  _validateString (value, name) {
+  _validateString(value, name) {
     if (typeof value !== 'string' || value.length === 0) {
       throw new Error(`Invalid ${name}: ${value}`)
     }
   }
 
-  async _checkBlobProgress (core, blobPointer) {
+  async _checkBlobProgress(core, blobPointer) {
     const totalBlocks = blobPointer.blockLength
     const totalBytes = blobPointer.byteLength
 
@@ -186,7 +200,7 @@ class QVACRegistryClient extends ReadyResource {
     return { cachedBlocks, totalBlocks, totalBytes }
   }
 
-  async _getBlobsCore (blobsCoreKey) {
+  async _getBlobsCore(blobsCoreKey) {
     let keyBuffer
     if (Buffer.isBuffer(blobsCoreKey)) {
       keyBuffer = blobsCoreKey
@@ -209,7 +223,82 @@ class QVACRegistryClient extends ReadyResource {
     return { core, blobs }
   }
 
-  async downloadModel (path, source, options = {}) {
+  /**
+   * Blocks while the swarm is suspended (app backgrounded), so a retry does not
+   * fire against a swarm that cannot connect yet and exhaust the retry budget.
+   * Bounded by RESUME_WAIT_MAX_MS; returns (and lets the retry proceed/fail) if
+   * the runtime never resumes.
+   */
+  async _waitForSwarmResumed(signal) {
+    if (!this.hyperswarm || !this.hyperswarm.suspended) return
+
+    const start = Date.now()
+    while (this.hyperswarm.suspended) {
+      if (signal && signal.aborted) throw new Error('Download cancelled')
+      if (Date.now() - start > RESUME_WAIT_MAX_MS) {
+        this.logger.warn('Swarm still suspended after resume wait; retrying anyway')
+        return
+      }
+      await new Promise((resolve) => setTimeout(resolve, RESUME_WAIT_POLL_MS))
+    }
+  }
+
+  /**
+   * Blocks until at least one peer is replicating the core, so a retry after a
+   * network drop waits for the network to actually return instead of firing
+   * (and timing out) against zero peers and burning the retry budget. Bounded
+   * by RESUME_WAIT_MAX_MS. No-op when peer info is unavailable.
+   */
+  async _waitForPeers(core, signal) {
+    if (!core || !Array.isArray(core.peers)) return
+    if (core.peers.length > 0) return
+
+    const start = Date.now()
+    while (core.peers.length === 0) {
+      if (signal && signal.aborted) throw new Error('Download cancelled')
+      if (Date.now() - start > RESUME_WAIT_MAX_MS) {
+        this.logger.warn('No peers after reconnect wait; retrying anyway')
+        return
+      }
+      await new Promise((resolve) => setTimeout(resolve, RESUME_WAIT_POLL_MS))
+    }
+  }
+
+  /**
+   * Re-establish peers for a blobs core before retrying a download. After the
+   * app backgrounds (or the network drops) the swarm connection for this core
+   * is gone; this waits for the swarm to resume and for a peer to be replicating
+   * the core, then re-runs the join + findingPeers + update sequence and awaits
+   * it. Resume itself is cheap: the next attempt reuses the blocks already
+   * cached in the core (the output file is re-streamed from those blocks, not
+   * appended to).
+   *
+   * Honours `signal`: a foreground cancel during the (bounded but up to
+   * RESUME_WAIT_MAX_MS) swarm/peer waits aborts promptly instead of blocking
+   * until peers return or the cap elapses.
+   */
+  async _reconnectCore(core, signal) {
+    if (!core || !this.hyperswarm) return
+    if (signal && signal.aborted) throw new Error('Download cancelled')
+
+    await this._waitForSwarmResumed(signal)
+
+    this.logger.debug('Re-establishing peers before download retry', {
+      discoveryKey: IdEnc.normalize(core.discoveryKey)
+    })
+
+    const done = core.findingPeers()
+    this.hyperswarm.join(core.discoveryKey, { client: true, server: false })
+    try {
+      await this.hyperswarm.flush()
+    } finally {
+      done()
+    }
+    await this._waitForPeers(core, signal)
+    await core.update()
+  }
+
+  async downloadModel(path, source, options = {}) {
     this._validateString(path, 'path')
     this._validateString(source, 'source')
 
@@ -217,7 +306,7 @@ class QVACRegistryClient extends ReadyResource {
       throw new Error(`Invalid options: ${typeof options}`)
     }
 
-    let core, blobs
+    let core, blobs, blockStart, blockEnd, rangeDownload
 
     try {
       this.logger.info('Downloading model', { path, source })
@@ -225,11 +314,17 @@ class QVACRegistryClient extends ReadyResource {
 
       const model = await this.getModel(path, source)
       if (!model) {
-        throw new QvacErrorRegistryClient({ code: ERR_CODES.MODEL_NOT_FOUND, adds: `Model not found: ${path} (source: ${source})` })
+        throw new QvacErrorRegistryClient({
+          code: ERR_CODES.MODEL_NOT_FOUND,
+          adds: `Model not found: ${path} (source: ${source})`
+        })
       }
 
       if (!model.blobBinding || !model.blobBinding.coreKey) {
-        throw new QvacErrorRegistryClient({ code: ERR_CODES.MODEL_NOT_FOUND, adds: 'Model missing blob binding' })
+        throw new QvacErrorRegistryClient({
+          code: ERR_CODES.MODEL_NOT_FOUND,
+          adds: 'Model missing blob binding'
+        })
       }
 
       this.logger.debug('Model metadata retrieved', { model })
@@ -251,31 +346,32 @@ class QVACRegistryClient extends ReadyResource {
 
       const totalSize = model.blobBinding.byteLength
 
-      const rangeDownload = core.download({
+      rangeDownload = core.download({
         start: model.blobBinding.blockOffset,
         length: model.blobBinding.blockLength
       })
 
-      const blockStart = model.blobBinding.blockOffset
-      const blockEnd = blockStart + model.blobBinding.blockLength
+      blockStart = model.blobBinding.blockOffset
+      blockEnd = blockStart + model.blobBinding.blockLength
 
       let artifact
       if (options.outputFile) {
         await withRetry(
           () => this._streamBlobToFile(blobs, core, model.blobBinding, options.outputFile, options),
           {
-            maxRetries: options.maxRetries != null ? options.maxRetries : DEFAULT_DOWNLOAD_MAX_RETRIES,
+            maxRetries: options.maxRetries ?? DEFAULT_DOWNLOAD_MAX_RETRIES,
             retryCodes: RETRIABLE_DOWNLOAD_CODES,
-            onRetry: () => fs.promises.unlink(options.outputFile).catch(() => {}),
+            // Wait for the swarm to resume + reconnect peers before retrying,
+            // so the retry doesn't immediately time out again against a dead
+            // swarm (e.g. after the app backgrounded). The core's cached blocks
+            // are not cleared until success, so the retry re-streams cheaply.
+            beforeRetry: () => this._reconnectCore(core, options.signal),
             logger: this.logger
           }
         )
         artifact = { path: options.outputFile, totalSize }
 
-        rangeDownload.destroy()
-        await this._clearBlobBlocks(core, blockStart, blockEnd)
-        if (blobs) await blobs.close()
-        if (core) await core.close()
+        await this._releaseDownload(core, blobs, rangeDownload, blockStart, blockEnd)
       } else {
         const stream = blobs.createReadStream(model.blobBinding, {
           wait: true,
@@ -283,27 +379,7 @@ class QVACRegistryClient extends ReadyResource {
         })
         artifact = { stream, totalSize }
 
-        const cleanup = async () => {
-          rangeDownload.destroy()
-          await this._clearBlobBlocks(core, blockStart, blockEnd)
-          if (blobs) {
-            try {
-              await blobs.close()
-            } catch (cleanupError) {
-              this.logger.warn('Error closing blob instance', { error: cleanupError.message })
-            }
-          }
-          if (core) {
-            try {
-              await core.close()
-            } catch (cleanupError) {
-              this.logger.warn('Error closing blob core', { error: cleanupError.message })
-            }
-          }
-          this.logger.debug('Blob resources closed after stream end')
-        }
-
-        stream.once('end', cleanup)
+        this._releaseOnStreamEnd(stream, core, blobs, rangeDownload, blockStart, blockEnd)
       }
 
       this.logger.info('Model downloaded successfully')
@@ -315,44 +391,38 @@ class QVACRegistryClient extends ReadyResource {
     } catch (error) {
       this.logger.error('Error downloading model', error)
 
-      if (blobs) {
-        try {
-          await blobs.close()
-        } catch (cleanupError) {
-          this.logger.warn('Error closing blob instance on error', { error: cleanupError.message })
-        }
-      }
-      if (core) {
-        try {
-          await core.close()
-        } catch (cleanupError) {
-          this.logger.warn('Error closing blob core on error', { error: cleanupError.message })
-        }
-      }
+      await this._releaseDownload(core, blobs, rangeDownload, blockStart, blockEnd)
 
       throw error
     }
   }
 
-  async downloadBlob (blobBinding, options = {}) {
+  async downloadBlob(blobBinding, options = {}) {
     if (!blobBinding || !blobBinding.coreKey) {
       throw new Error('Invalid blobBinding: coreKey is required')
     }
-    if (typeof blobBinding.blockOffset !== 'number' ||
-        typeof blobBinding.blockLength !== 'number' ||
-        typeof blobBinding.byteLength !== 'number') {
-      throw new Error('Invalid blobBinding: blockOffset, blockLength, and byteLength are required numbers')
+    if (
+      typeof blobBinding.blockOffset !== 'number' ||
+      typeof blobBinding.blockLength !== 'number' ||
+      typeof blobBinding.byteLength !== 'number'
+    ) {
+      throw new Error(
+        'Invalid blobBinding: blockOffset, blockLength, and byteLength are required numbers'
+      )
     }
 
     if (options && typeof options !== 'object') {
       throw new Error(`Invalid options: ${typeof options}`)
     }
 
-    let core, blobs
+    let core, blobs, blockStart, blockEnd, rangeDownload
 
     try {
       this.logger.info('Downloading blob directly', {
-        coreKey: typeof blobBinding.coreKey === 'string' ? blobBinding.coreKey.slice(0, 12) + '...' : '(buffer)',
+        coreKey:
+          typeof blobBinding.coreKey === 'string'
+            ? blobBinding.coreKey.slice(0, 12) + '...'
+            : '(buffer)',
         blockOffset: blobBinding.blockOffset,
         blockLength: blobBinding.blockLength,
         byteLength: blobBinding.byteLength
@@ -383,10 +453,10 @@ class QVACRegistryClient extends ReadyResource {
       }
       const totalSize = blobBinding.byteLength
 
-      const blockStart = pointer.blockOffset
-      const blockEnd = blockStart + pointer.blockLength
+      blockStart = pointer.blockOffset
+      blockEnd = blockStart + pointer.blockLength
 
-      const rangeDownload = core.download({
+      rangeDownload = core.download({
         start: pointer.blockOffset,
         length: pointer.blockLength
       })
@@ -396,18 +466,17 @@ class QVACRegistryClient extends ReadyResource {
         await withRetry(
           () => this._streamBlobToFile(blobs, core, pointer, options.outputFile, options),
           {
-            maxRetries: options.maxRetries != null ? options.maxRetries : DEFAULT_DOWNLOAD_MAX_RETRIES,
+            maxRetries: options.maxRetries ?? DEFAULT_DOWNLOAD_MAX_RETRIES,
             retryCodes: RETRIABLE_DOWNLOAD_CODES,
-            onRetry: () => fs.promises.unlink(options.outputFile).catch(() => {}),
+            // Wait for swarm resume + peer reconnect before retrying (see
+            // downloadModel). Cached blocks are reused; the file is re-streamed.
+            beforeRetry: () => this._reconnectCore(core, options.signal),
             logger: this.logger
           }
         )
         artifact = { path: options.outputFile, totalSize }
 
-        rangeDownload.destroy()
-        await this._clearBlobBlocks(core, blockStart, blockEnd)
-        if (blobs) await blobs.close()
-        if (core) await core.close()
+        await this._releaseDownload(core, blobs, rangeDownload, blockStart, blockEnd)
       } else {
         const stream = blobs.createReadStream(pointer, {
           wait: true,
@@ -415,23 +484,7 @@ class QVACRegistryClient extends ReadyResource {
         })
         artifact = { stream, totalSize }
 
-        const cleanup = async () => {
-          rangeDownload.destroy()
-          await this._clearBlobBlocks(core, blockStart, blockEnd)
-          if (blobs) {
-            try { await blobs.close() } catch (e) {
-              this.logger.warn('Error closing blob instance', { error: e.message })
-            }
-          }
-          if (core) {
-            try { await core.close() } catch (e) {
-              this.logger.warn('Error closing blob core', { error: e.message })
-            }
-          }
-          this.logger.debug('Blob resources closed after stream end')
-        }
-
-        stream.once('end', cleanup)
+        this._releaseOnStreamEnd(stream, core, blobs, rangeDownload, blockStart, blockEnd)
       }
 
       this.logger.info('Blob download complete (direct)')
@@ -440,33 +493,96 @@ class QVACRegistryClient extends ReadyResource {
     } catch (error) {
       this.logger.error('Error downloading blob directly', error)
 
-      if (blobs) {
-        try { await blobs.close() } catch (e) {
-          this.logger.warn('Error closing blob instance on error', { error: e.message })
-        }
+      await this._releaseDownload(core, blobs, rangeDownload, blockStart, blockEnd)
+
+      throw error
+    }
+  }
+
+  _releaseOnStreamEnd(stream, core, blobs, rangeDownload, blockStart, blockEnd) {
+    let released = false
+
+    // 'close' also covers a destroyed or errored stream; on 'end' alone a
+    // cancelled stream download would never free its blocks.
+    const release = () => {
+      if (released) return
+      released = true
+      return this._releaseDownload(core, blobs, rangeDownload, blockStart, blockEnd).catch((e) =>
+        this.logger.warn('Error releasing blob resources', { error: e.message })
+      )
+    }
+
+    stream.once('end', release)
+    stream.once('close', release)
+  }
+
+  async _releaseDownload(core, blobs, rangeDownload, blockStart, blockEnd) {
+    // Hypercore can commit in-flight responses after a range is destroyed.
+    if (rangeDownload) rangeDownload.destroy()
+
+    if (core && blockStart !== undefined) {
+      if (rangeDownload) await this._waitForInflightBlocks(core)
+      await this._clearBlobBlocks(core, blockStart, blockEnd)
+    }
+    if (blobs) {
+      try {
+        await blobs.close()
+      } catch (e) {
+        this.logger.warn('Error closing blob instance', { error: e.message })
       }
-      if (core) {
-        try { await core.close() } catch (e) {
-          this.logger.warn('Error closing blob core on error', { error: e.message })
-        }
+    }
+    if (core) {
+      try {
+        await core.close()
+      } catch (e) {
+        this.logger.warn('Error closing blob core', { error: e.message })
       }
+    }
 
-      throw error
+    this.logger.debug('Blob resources released')
+  }
+
+  async _waitForInflightBlocks(core) {
+    if (!Array.isArray(core.peers)) return
+
+    const timeoutMs = this._inflightDrainTimeoutMs ?? INFLIGHT_DRAIN_TIMEOUT_MS
+    const pollMs = this._inflightDrainPollMs ?? INFLIGHT_DRAIN_POLL_MS
+    const deadline = Date.now() + timeoutMs
+    while (core.peers.some((peer) => peer.inflight > 0 || peer.dataProcessing > 0)) {
+      if (Date.now() >= deadline) {
+        this.logger.warn('Timed out waiting for in-flight blob blocks before clearing', {
+          timeoutMs,
+          peers: core.peers.map((peer, index) => ({
+            peer: index,
+            inflight: peer.inflight,
+            dataProcessing: peer.dataProcessing
+          }))
+        })
+        return
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollMs))
     }
   }
 
-  async _clearBlobBlocks (core, start, end) {
+  async _clearBlobBlocks(core, start, end) {
     try {
       const cleared = await core.clear(start, end, { diff: true })
       await core.compact()
-      this.logger.info('Cleared blob blocks from corestore', { start, end, blocks: cleared ? cleared.blocks : end - start })
+      this.logger.info('Cleared blob blocks from corestore', {
+        start,
+        end,
+        blocks: cleared ? cleared.blocks : end - start
+      })
     } catch (err) {
       this.logger.warn('Failed to clear blob blocks from corestore', { error: err.message })
     }
   }
 
-  async _streamBlobToFile (blobs, core, blobPointer, filePath, options) {
-    const { cachedBlocks, totalBlocks, totalBytes } = await this._checkBlobProgress(core, blobPointer)
+  async _streamBlobToFile(blobs, core, blobPointer, filePath, options) {
+    const { cachedBlocks, totalBlocks, totalBytes } = await this._checkBlobProgress(
+      core,
+      blobPointer
+    )
 
     this.logger.debug('Blob progress before download', {
       cachedBlocks,
@@ -488,7 +604,10 @@ class QVACRegistryClient extends ReadyResource {
     }
 
     const progressHandler = (index, bytes) => {
-      if (index >= blobPointer.blockOffset && index < blobPointer.blockOffset + blobPointer.blockLength) {
+      if (
+        index >= blobPointer.blockOffset &&
+        index < blobPointer.blockOffset + blobPointer.blockLength
+      ) {
         downloadedBytes += bytes
         const capped = Math.min(downloadedBytes, totalBytes)
         if (options.onProgress) {
@@ -533,11 +652,15 @@ class QVACRegistryClient extends ReadyResource {
             reject(new Error('Download cancelled'))
             return
           }
-          options.signal.addEventListener('abort', () => {
-            stream.destroy()
-            writeStream.destroy()
-            reject(new Error('Download cancelled'))
-          }, { once: true })
+          options.signal.addEventListener(
+            'abort',
+            () => {
+              stream.destroy()
+              writeStream.destroy()
+              reject(new Error('Download cancelled'))
+            },
+            { once: true }
+          )
         }
       })
     } finally {
@@ -546,7 +669,7 @@ class QVACRegistryClient extends ReadyResource {
     }
   }
 
-  async suspend (opts = {}) {
+  async suspend(opts = {}) {
     this.logger.debug('suspend called')
 
     if (!this.opened || this.closing) {
@@ -564,7 +687,7 @@ class QVACRegistryClient extends ReadyResource {
     this.logger.debug('QVACRegistryClient suspended')
   }
 
-  async resume (opts = {}) {
+  async resume(opts = {}) {
     this.logger.debug('resume called')
 
     if (!this.opened || this.closing) {
@@ -582,7 +705,7 @@ class QVACRegistryClient extends ReadyResource {
     this.logger.debug('QVACRegistryClient resumed')
   }
 
-  async _close () {
+  async _close() {
     this.logger.debug('_close called')
 
     if (this._metadataReady) {

package/lib/config.js

@@ -9,12 +9,12 @@ const path = require('#path')
 const DEFAULT_REGISTRY_CORE_KEY = 'uf1fm44uzockp6azhcdiqt1esjgm65fwtimsh946e8kwysdes9ko'
 
 class RegistryConfig {
-  constructor (opts = {}) {
+  constructor(opts = {}) {
     this.logger = new Logger(opts.logger)
     this.logger.debug('RegistryConfig initialized', { opts })
   }
 
-  getRegistryStorage (providedPath) {
+  getRegistryStorage(providedPath) {
     if (providedPath) {
       this.logger.debug('getRegistryStorage called with providedPath', { providedPath })
       return providedPath
@@ -26,14 +26,17 @@ class RegistryConfig {
     return result
   }
 
-  _createTempStoragePath () {
+  _createTempStoragePath() {
     const tmpBase = os.tmpdir()
-    const storageDir = path.join(tmpBase, `qvac-registry-client-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`)
+    const storageDir = path.join(
+      tmpBase,
+      `qvac-registry-client-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+    )
     this.logger.debug('Created temp storage path', { storageDir })
     return storageDir
   }
 
-  getRegistryCoreKey (providedKey) {
+  getRegistryCoreKey(providedKey) {
     if (providedKey) {
       this.logger.debug('getRegistryCoreKey called with providedKey', { providedKey })
       return providedKey

package/lib/logger.js

@@ -1,7 +1,7 @@
 'use strict'
 
 class Logger {
-  constructor (opts = {}) {
+  constructor(opts = {}) {
     this.level = opts.level || 'info'
     this.name = opts.name || 'QVACRegistryClient'
     this.enabled = opts.enabled !== false
@@ -14,30 +14,30 @@ class Logger {
     }
   }
 
-  _shouldLog (level) {
+  _shouldLog(level) {
     if (!this.enabled) return false
     return this.levels[level] >= this.levels[this.level]
   }
 
-  _log (level, ...args) {
+  _log(level, ...args) {
     if (!this._shouldLog(level)) return
     const prefix = `[${this.name}] [${level.toUpperCase()}]`
     console[level](prefix, ...args)
   }
 
-  debug (...args) {
+  debug(...args) {
     this._log('debug', ...args)
   }
 
-  info (...args) {
+  info(...args) {
     this._log('info', ...args)
   }
 
-  warn (...args) {
+  warn(...args) {
     this._log('warn', ...args)
   }
 
-  error (...args) {
+  error(...args) {
     this._log('error', ...args)
   }
 }

package/lib/profiler.js

@@ -13,7 +13,7 @@ const { RegistryDatabase } = require('@qvac/registry-schema')
  * Normalize a blob core key into a Buffer regardless of input format.
  * Handles raw Buffer, { data: [...] } objects from HyperDB, and z32/hex strings.
  */
-function decodeCoreKey (key) {
+function decodeCoreKey(key) {
   if (Buffer.isBuffer(key)) return key
   if (typeof key === 'object' && key !== null && key.data) {
     return Buffer.from(key.data)
@@ -25,7 +25,7 @@ function decodeCoreKey (key) {
  * Collect a snapshot of network, connection, and hypercore stats.
  * All fields are plain values suitable for logging or formatting.
  */
-function collectStats (swarmStats, hypercoreStats, blobCore, elapsedSec) {
+function collectStats(swarmStats, hypercoreStats, blobCore, elapsedSec) {
   const bytesRx = swarmStats.dhtStats.udxBytesReceived
   const bytesTx = swarmStats.dhtStats.udxBytesTransmitted
 
@@ -71,7 +71,7 @@ function collectStats (swarmStats, hypercoreStats, blobCore, elapsedSec) {
 /**
  * Format a stats snapshot into a human-readable string.
  */
-function formatStats (stats) {
+function formatStats(stats) {
   const n = stats.network
   const c = stats.connection
   const h = stats.hypercore
@@ -88,7 +88,14 @@ function formatStats (stats) {
   lines += '  Attempted:  ' + c.attempted + '\n'
   lines += '  Opened:     ' + c.opened + '\n'
   lines += '  Closed:     ' + c.closed + '\n'
-  lines += '  Issues:     rto=' + c.rtos + ' fast-recoveries=' + c.fastRecoveries + ' retransmits=' + c.retransmits + '\n'
+  lines +=
+    '  Issues:     rto=' +
+    c.rtos +
+    ' fast-recoveries=' +
+    c.fastRecoveries +
+    ' retransmits=' +
+    c.retransmits +
+    '\n'
   lines += 'Hypercore\n'
   lines += '  Blob core: ' + h.contiguousLength + ' / ' + h.length + ' (contiguous / length)\n'
   lines += '  Hotswaps:  ' + h.hotswaps + '\n'
@@ -106,7 +113,7 @@ function formatStats (stats) {
 /**
  * Format a final download summary into a human-readable string.
  */
-function formatSummary (opts) {
+function formatSummary(opts) {
   let lines = '='.repeat(50) + '\n'
   lines += 'FINAL SUMMARY\n'
   lines += '='.repeat(50) + '\n'
@@ -133,7 +140,7 @@ function formatSummary (opts) {
  * @param {function} [opts.onLog] - Called with (message) for log output; defaults to console.log
  * @returns {Promise<object>} Summary with timing and stats
  */
-async function profileDownload (opts) {
+async function profileDownload(opts) {
   // Lazy-loaded: these Node builtins don't exist in Bare runtime,
   // so they must not be required at the top level or unit tests break.
   const os = require('#os')
@@ -177,7 +184,9 @@ async function profileDownload (opts) {
   const cleanupResources = async () => {
     await swarm.destroy()
     await store.close()
-    try { fs.rmSync(tmpdir, { recursive: true, force: true }) } catch {}
+    try {
+      fs.rmSync(tmpdir, { recursive: true, force: true })
+    } catch {}
   }
 
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/registry-client",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "QVAC Registry client library for read-only queries via Hyperswarm",
   "license": "Apache-2.0",
   "repository": {
@@ -47,13 +47,15 @@
     "test:unit": "brittle tests/unit/*.test.js",
     "test:unit:bare": "brittle-bare tests/unit/*.test.js",
     "test": "npm run test:unit && npm run test:integration",
-    "lint": "standard",
-    "lint:fix": "standard --fix",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "lint": "lunte",
+    "lint:fix": "lunte --fix",
     "typecheck": "npx tsc --noEmit"
   },
   "dependencies": {
     "@qvac/error": "^0.1.0",
-    "@qvac/registry-schema": "^0.3.0",
+    "@qvac/registry-schema": "^0.4.0",
     "b4a": "^1.6.7",
     "bare-fs": "^4.5.2",
     "bare-os": "^3.6.2",
@@ -72,7 +74,9 @@
   "devDependencies": {
     "brittle": "^3.4.0",
     "dotenv": "^17.2.3",
-    "standard": "^17.1.0",
+    "lunte": "^1.8.4",
+    "prettier": "^3.9.6",
+    "prettier-config-holepunch": "^2.0.0",
     "test-tmp": "^1.4.0",
     "typescript": "^5.9.3"
   }

package/utils/env.js

@@ -1,6 +1,6 @@
 'use strict'
 
-function getEnv (key, defaultValue = undefined) {
+function getEnv(key, defaultValue = undefined) {
   if (typeof process !== 'undefined' && process.env && process.env[key] !== undefined) {
     return process.env[key]
   }

package/utils/error.js

@@ -3,7 +3,7 @@
 const { QvacErrorBase, addCodes } = require('@qvac/error')
 const { name, version } = require('../package.json')
 
-class QvacErrorRegistryClient extends QvacErrorBase { }
+class QvacErrorRegistryClient extends QvacErrorBase {}
 
 // This library has error code range from 19,001 to 20,000
 const ERR_CODES = Object.freeze({
@@ -12,23 +12,26 @@ const ERR_CODES = Object.freeze({
   MODEL_NOT_FOUND: 19003
 })
 
-addCodes({
-  [ERR_CODES.FAILED_TO_CONNECT]: {
-    name: 'FAILED_TO_CONNECT',
-    message: (message) => `Failed to connect to registry, error: ${message}`
+addCodes(
+  {
+    [ERR_CODES.FAILED_TO_CONNECT]: {
+      name: 'FAILED_TO_CONNECT',
+      message: (message) => `Failed to connect to registry, error: ${message}`
+    },
+    [ERR_CODES.FAILED_TO_CLOSE]: {
+      name: 'FAILED_TO_CLOSE',
+      message: (message) => `Failed to close registry, error: ${message}`
+    },
+    [ERR_CODES.MODEL_NOT_FOUND]: {
+      name: 'MODEL_NOT_FOUND',
+      message: (message) => `Model not found, error: ${message}`
+    }
   },
-  [ERR_CODES.FAILED_TO_CLOSE]: {
-    name: 'FAILED_TO_CLOSE',
-    message: (message) => `Failed to close registry, error: ${message}`
-  },
-  [ERR_CODES.MODEL_NOT_FOUND]: {
-    name: 'MODEL_NOT_FOUND',
-    message: (message) => `Model not found, error: ${message}`
+  {
+    name,
+    version
   }
-}, {
-  name,
-  version
-})
+)
 
 module.exports = {
   ERR_CODES,

package/utils/retry.js

@@ -8,11 +8,14 @@
  * @param {number} [opts.maxRetries=3] - Maximum number of attempts (including the first)
  * @param {string[]} [opts.retryCodes=[]] - Error codes that trigger a retry
  * @param {() => Promise<void>} [opts.onRetry] - Called before each retry attempt (e.g. cleanup)
+ * @param {() => Promise<void>} [opts.beforeRetry] - Awaited before the next attempt runs.
+ *   Use to re-establish prerequisites (e.g. wait for peers to reconnect) so the
+ *   retry doesn't immediately fail again against a dead connection.
  * @param {{ warn: Function }} [opts.logger] - Logger instance for retry warnings
  * @returns {Promise<unknown>}
  */
-async function withRetry (fn, opts = {}) {
-  const { maxRetries = 3, retryCodes = [], onRetry, logger } = opts
+async function withRetry(fn, opts = {}) {
+  const { maxRetries = 3, retryCodes = [], onRetry, beforeRetry, logger } = opts
 
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
     try {
@@ -20,8 +23,10 @@ async function withRetry (fn, opts = {}) {
     } catch (err) {
       const isRetriable = retryCodes.length > 0 && retryCodes.includes(err && err.code)
       if (!isRetriable || attempt >= maxRetries) throw err
-      logger && logger.warn(`Retrying after ${err.code} (attempt ${attempt}/${maxRetries}): ${err.message}`)
+      logger &&
+        logger.warn(`Retrying after ${err.code} (attempt ${attempt}/${maxRetries}): ${err.message}`)
       if (onRetry) await onRetry()
+      if (beforeRetry) await beforeRetry()
     }
   }
 }