@wildo-ai/wildo-module-client 1.1.4 → 1.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildo-ai/wildo-module-client",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Module-registry runtime services consumed by wildo-cli and the dev companion (Phase 0.5 skeleton)",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Wildo AI",
@@ -30,7 +30,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@wildo-ai/platform-config-lib": "1.1.4"
+    "@wildo-ai/platform-config-lib": "1.1.6"
   },
   "devDependencies": {
     "@types/node": "^24.0.15",

package/src/__tests__/lockfile-repair.service.test.ts

@@ -1,5 +1,5 @@
 /**
- * Phase 2 tests for `LockfileRepairService`.
+ * Read-only inspector tests for `LockfileRepairService`.
  *
  * The service is read-only and produces a structured report.
  * Tests pin every finding kind:
@@ -7,7 +7,7 @@
  *   - malformed envelope → error finding.
  *   - malformed modules section → error finding.
  *   - lockfile entry pointing at a missing file → warn finding.
- *   - lockfile entry with non-sha256 digest → warn finding.
+ * Malformed-digest dispatch and healthy/structure controls are covered by the CLI repair-contract suite.
  */
 
 import { promises as fs } from 'node:fs';

package/src/__tests__/module-adopter.service.test.ts

@@ -13,6 +13,7 @@ import { promises as fs } from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ModuleManifestSchema } from '@wildo-ai/platform-config-lib';
 import { ModuleAdopterService } from '../services/module-adopter.service';
 
 let saasRoot: string;
@@ -25,7 +26,8 @@ afterEach(async () => {
   await fs.rm(saasRoot, { recursive: true, force: true });
 });
 
-const manifest = {
+// Parsed, so the fixture has the manifest's OUTPUT type: defaults (`kind`, every boundary layer) included.
+const manifest = ModuleManifestSchema.parse({
   id: 'acme/billing',
   version: '1.2.3',
   boundaries: {
@@ -36,7 +38,7 @@ const manifest = {
     minions: [],
     workers: [],
   },
-};
+});
 
 async function seedFile(rel: string, contents: string): Promise<void> {
   const abs = path.join(saasRoot, rel);
@@ -67,10 +69,10 @@ describe('ModuleAdopterService.discoverModuleFiles', () => {
 
   it('returns an empty plan when the manifest declares no boundaries', async () => {
     await seedFile('anywhere.ts', 'x');
-    const plan = await ModuleAdopterService.discoverModuleFiles(saasRoot, {
+    const plan = await ModuleAdopterService.discoverModuleFiles(saasRoot, ModuleManifestSchema.parse({
       id: 'acme/x',
       version: '0.0.1',
-    });
+    }));
     expect(plan.files).toEqual([]);
     expect(plan.emptyBoundaries).toEqual([]);
   });

package/src/__tests__/module-packager.service.test.ts

@@ -23,6 +23,7 @@ import {
   getModuleStagingPaths,
   assertWithinBoundaries,
 } from '../services/module-packager.service';
+import { ModuleManifestSchema, RegistryBoundaryViolationError } from '@wildo-ai/platform-config-lib';
 
 let saasRoot: string;
 
@@ -34,7 +35,8 @@ afterEach(async () => {
   await fs.rm(saasRoot, { recursive: true, force: true });
 });
 
-const baseManifest = (id = 'acme/billing', version = '1.2.3') => ({
+// Parsed, so the fixture has the manifest's OUTPUT type: defaults (`kind`, every boundary layer) included.
+const baseManifest = (id = 'acme/billing', version = '1.2.3') => ModuleManifestSchema.parse({
   id,
   version,
   description: 'Billing module',
@@ -107,9 +109,18 @@ describe('assertWithinBoundaries (KD-12)', () => {
     expect(result.endsWith('shared-lib/src/modules/acme-billing/index.ts')).toBe(true);
   });
 
-  it('skips boundary checks when no boundaries are declared (manifest.boundaries undefined)', () => {
-    const result = assertWithinBoundaries(saasRoot, 'acme/billing', 'anywhere.ts', undefined);
-    expect(result.endsWith('anywhere.ts')).toBe(true);
+  // A module that declares no boundary may write nowhere. This used to return early and admit every
+  // path in the application — the fail-open reading of an absent declaration.
+  it('refuses every path when no boundaries are declared (manifest.boundaries undefined)', () => {
+    expect(() => assertWithinBoundaries(saasRoot, 'acme/billing', 'anywhere.ts', undefined)).toThrow(
+      RegistryBoundaryViolationError,
+    );
+  });
+
+  it('refuses a dot-file inside a declared boundary (a generated .env must never be packed)', () => {
+    expect(() =>
+      assertWithinBoundaries(saasRoot, 'acme/billing', 'shared-lib/src/modules/acme-billing/.env', baseManifest().boundaries),
+    ).toThrow(RegistryBoundaryViolationError);
   });
 });
 
@@ -218,41 +229,32 @@ describe('ModulePackagerService.computeStagingDigest', () => {
 });
 
 /**
- * 7th-pass C-L1 — root edge case for `isPathInside`. The helper is
- * invoked indirectly through `assertWithinBoundaries`; we exercise
- * the degenerate filesystem-root case by pointing `saasRoot` at `/`
- * and confirming a child path inside `/` is accepted as "within
- * boundaries" when the manifest declares `boundaries.shared: ['./']`
- * (relative path that resolves to `/`).
- *
- * Vanishingly unlikely in production (containerized SaaS roots are
- * never literally `/`) but the helper is also reusable for zip-slip
- * guards where the assumption is weaker — pinning the behavior
- * prevents a future "tighten startsWith" refactor from rejecting
- * every child.
+ * 7th-pass C-L1 — root edge case for `isPathInside`, which treats the filesystem root as containing
+ * every absolute path. Exercised with a LEGAL boundary: the pin used to declare `shared: ['.']`, a
+ * boundary the manifest contract now refuses ("the whole application root"), and passed only because
+ * the typed object never went through the schema.
  */
 describe('assertWithinBoundaries — root edge case (C-L1)', () => {
-  it('accepts a child path when saasRoot is the filesystem root', () => {
-    // Use POSIX path.sep as the boundary; the helper resolves
-    // `path.resolve('/', '.')` → `/` and then `isPathInside('/foo', '/')`
-    // → true via the new root special-case.
-    const manifestWithRootBoundary = {
-      ...baseManifest(),
-      boundaries: {
-        specifications: [],
-        shared: ['.'],
-        frontend: [],
-        backend: [],
-        minions: [],
-        workers: [],
-      },
-    };
-    // Run only on POSIX; Windows root is `C:\` and tests run on
-    // POSIX CI.
+  it('accepts a file inside a declared boundary when saasRoot is the filesystem root', () => {
+    // POSIX only; Windows root is `C:\` and tests run on POSIX CI.
     if (path.sep === '/') {
       expect(() =>
-        assertWithinBoundaries('/', 'acme/billing', 'foo/bar.ts', manifestWithRootBoundary.boundaries),
+        assertWithinBoundaries('/', 'acme/billing', 'shared-lib/src/modules/acme-billing/a.ts', baseManifest().boundaries),
       ).not.toThrow();
     }
   });
 });
+
+describe('getModuleStagingPaths — the staging root a recursive delete runs on', () => {
+  // `stageFresh` deletes this path recursively. `a/../../../..` passed the old "contains a `/`" rule
+  // and resolved to the application root.
+  it.each(['a/../../../..', 'acme', 'acme/billing/extra', 'acme/.hidden'])('refuses module id %s', (id) => {
+    expect(() => getModuleStagingPaths(saasRoot, id)).toThrow(TypeError);
+  });
+
+  it('resolves a well-formed id below the artifacts directory', () => {
+    expect(getModuleStagingPaths(saasRoot, 'acme/billing').stagingRoot).toBe(
+      path.join(saasRoot, MODULES_ARTIFACTS_RELATIVE_DIR, 'acme/billing'),
+    );
+  });
+});

package/src/__tests__/provider-sync-runner.test.ts

@@ -47,6 +47,18 @@ describe('runProviderSync (dry-run)', () => {
   });
 });
 
+describe('runProviderSync (a chatty child)', () => {
+  // `wildo config sync` prints progress. Its stdout used to be PIPED and never read, so once the child
+  // wrote more than the OS pipe buffer (~64 KB) it blocked on the write, never exited, and the runner
+  // reported a timeout for a sync that had in fact finished its work.
+  it('completes when the child writes far more than a pipe buffer to stdout', async () => {
+    const stub = await writeStub('wildo', "#!/bin/sh\nhead -c 1048576 /dev/zero | tr '\\000' x\nexit 0\n");
+    const result = await runProviderSync({ saasRoot, reason: 'install', wildoBinPath: stub, timeoutMs: 5000 });
+    expect(result.mode).toBe('shell-out');
+    expect(result.exitCode).toBe(0);
+  }, 20000);
+});
+
 describe('runProviderSync (shell-out — success)', () => {
   it('returns mode:shell-out and the stub exit code (0)', async () => {
     const stub = await writeStub('wildo', '#!/bin/sh\nexit 0\n');

package/src/__tests__/registry-lockfile.service.test.ts

@@ -14,7 +14,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { RegistryLockfileService } from '../services/registry-lockfile.service';
 // L6 (third-pass review): the symbol is no longer re-exported from
 // `wildo-module-client`; import it directly from `platform-config-lib`.
-import { WILDO_SAAS_LOCK_RELATIVE_PATH } from '@wildo-ai/platform-config-lib';
+import { RegistryModulesLockEntrySchema, WILDO_SAAS_LOCK_RELATIVE_PATH } from '@wildo-ai/platform-config-lib';
 
 let saasRoot: string;
 
@@ -86,7 +86,7 @@ describe('RegistryLockfileService', () => {
       ...current,
       installed: {
         ...current.installed,
-        'acme/billing': {
+        'acme/billing': RegistryModulesLockEntrySchema.parse({
           moduleId: 'acme/billing',
           registryId: 'wildo',
           registryUrl: 'https://registry.wildo.ai',
@@ -96,7 +96,7 @@ describe('RegistryLockfileService', () => {
           installedAt: '2026-05-05T12:00:00.000Z',
           files: [],
           source: 'install',
-        },
+        }),
       },
     }));
 

package/src/__tests__/registry-server-client.test.ts

@@ -14,11 +14,17 @@ import {
   RegistryArtifactIntegrityMismatchError,
   RegistryAuthForbiddenError,
   RegistryAuthRequiredError,
+  RegistryCredentialRejectedError,
   RegistryMalformedPayloadError,
   RegistryModuleNotFoundError,
+  RegistryRateLimitedError,
+  RegistryUnexpectedStatusError,
   RegistryVersionNotFoundError,
+  RegistryYankStateConflictError,
+  RegistryYankVerb,
 } from '@wildo-ai/platform-config-lib';
 import { RegistryServerClient } from '../services/registry-server-client';
+import { ModuleKind, type ModuleSearchFilter } from '@wildo-ai/platform-config-lib';
 
 interface TestServer {
   baseUrl: string;
@@ -151,6 +157,32 @@ describe('RegistryServerClient.resolve', () => {
     ).rejects.toBeInstanceOf(RegistryAuthRequiredError);
   });
 
+  it('tells a REJECTED key from a missing one: a 401 to a request that sent a key is CredentialRejected (#1759 review)', async () => {
+    svc = await startServer((req, res) => {
+      res.writeHead(401);
+      res.end();
+    });
+    const error = await RegistryServerClient.resolve(
+      { baseUrl: svc.baseUrl, authToken: 'sk_org_revoked' },
+      { domain: 'acme', moduleId: 'acme/billing', range: '^1.0.0' },
+    ).catch((err: unknown) => err);
+    expect(error).toBeInstanceOf(RegistryCredentialRejectedError);
+    expect(error).not.toBeInstanceOf(RegistryAuthRequiredError);
+  });
+
+  it('types a 429 as RegistryRateLimitedError, carrying Retry-After seconds', async () => {
+    svc = await startServer((req, res) => {
+      res.writeHead(429, { 'retry-after': '600' });
+      res.end();
+    });
+    const error = await RegistryServerClient.resolve(
+      { baseUrl: svc.baseUrl, authToken: 'sk_org_x' },
+      { domain: 'acme', moduleId: 'acme/billing', range: '^1.0.0' },
+    ).catch((err: unknown) => err);
+    expect(error).toBeInstanceOf(RegistryRateLimitedError);
+    expect((error as RegistryRateLimitedError).retryAfterSeconds).toBe(600);
+  });
+
   it('throws RegistryAuthForbiddenError on 403', async () => {
     svc = await startServer((req, res) => {
       res.writeHead(403);
@@ -287,6 +319,38 @@ describe('RegistryServerClient — parseJsonOrThrow (malformed 2xx body)', () =>
   });
 });
 
+describe('RegistryServerClient.search — manifest filters (#2014)', () => {
+  it('sends only the filters given, and reads a provider hit with its kind and provider facts', async () => {
+    let requested = '';
+    svc = await startServer((req, res) => {
+      requested = req.url ?? '';
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ hits: [
+        { moduleId: 'wildo/vlm-run', latestVersion: '2.0.0', kind: 'provider', provider: { ref: 'vlm-run', maturity: 'adopted', engineCapabilities: ['AI_DOCUMENT_EXTRACTION'] } },
+        // A registry deployed before #2014 sends neither field.
+        { moduleId: 'acme/billing', latestVersion: '1.0.0' },
+      ] }));
+    });
+    const hits = await RegistryServerClient.search(
+      { baseUrl: svc.baseUrl },
+      { domain: 'wildo', query: 'vlm', filter: { kind: ModuleKind.PROVIDER, engineCapability: 'AI_DOCUMENT_EXTRACTION' as ModuleSearchFilter['engineCapability'] } },
+    );
+    expect(requested).toBe('/v1/registry/wildo/modules?q=vlm&kind=provider&engineCapability=AI_DOCUMENT_EXTRACTION');
+    expect(hits[0]?.provider?.engineCapabilities).toEqual(['AI_DOCUMENT_EXTRACTION']);
+    // Re-applied client-side (#2014 review F9): a server that ignored the filter cannot make it fail open.
+    expect(hits.map((hit) => hit.moduleId)).toEqual(['wildo/vlm-run']);
+  });
+
+  it('keeps every hit when no filter is given, including one from a server that predates #2014', async () => {
+    svc = await startServer((_req, res) => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ hits: [{ moduleId: 'acme/billing', latestVersion: '1.0.0' }] }));
+    });
+    const hits = await RegistryServerClient.search({ baseUrl: svc.baseUrl }, { domain: 'wildo', query: '' });
+    expect(hits.map((hit) => hit.kind ?? 'absent')).toEqual(['absent']);
+  });
+});
+
 /**
  * 7th-pass C-M1: `download()` argument-shape violation. Caller passes
  * a malformed `expectedDigest` — must throw `TypeError` (not Zod's
@@ -310,3 +374,68 @@ describe('RegistryServerClient.download — malformed expectedDigest (C-M1)', ()
     ).rejects.toBeInstanceOf(TypeError);
   });
 });
+
+describe('RegistryServerClient.yank / unyank (#1758)', () => {
+  it('posts the version and reason to the verb route, and returns where latest points afterwards', async () => {
+    let seen: { url?: string; method?: string; body?: unknown; auth?: string } = {};
+    svc = await startServer(async (req, res) => {
+      let raw = '';
+      for await (const chunk of req) raw += chunk;
+      seen = { url: req.url, method: req.method, body: JSON.parse(raw), auth: req.headers.authorization };
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, latest: '1.1.0' }));
+    });
+    const result = await RegistryServerClient.yank(
+      { baseUrl: svc.baseUrl, authToken: 'sk_org_k' },
+      { domain: 'acme', moduleId: 'acme/billing', version: '1.2.0', reason: 'broken migration' },
+    );
+    expect(result).toEqual({ latest: '1.1.0' });
+    expect(seen).toEqual({
+      url: '/v1/registry/acme/modules/acme%2Fbilling/yank',
+      method: 'POST',
+      body: { version: '1.2.0', reason: 'broken migration' },
+      auth: 'Bearer sk_org_k',
+    });
+  });
+
+  it('reports a module whose releases are all yanked as latest: null', async () => {
+    svc = await startServer((req, res) => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, latest: null }));
+    });
+    expect(await RegistryServerClient.unyank({ baseUrl: svc.baseUrl }, { domain: 'acme', moduleId: 'acme/billing', version: '1.0.0' }))
+      .toEqual({ latest: null });
+  });
+
+  /** The engine's sanitized error envelope, as the registry sends it — wire values pinned on purpose. */
+  const conflictBody = (customMessageReference: string, code?: string) =>
+    JSON.stringify({ error: { type: 'CONFLICT', customMessageReference, ...(code ? { details: { code } } : {}) } });
+
+  it.each([RegistryYankVerb.YANK, RegistryYankVerb.UNYANK] as const)('types a release-state 409 on %s as the state conflict it is', async (verb) => {
+    svc = await startServer((req, res) => {
+      res.writeHead(409, { 'content-type': 'application/json' });
+      res.end(conflictBody('conflict', 'registry_release_state'));
+    });
+    const call = verb === RegistryYankVerb.YANK ? RegistryServerClient.yank : RegistryServerClient.unyank;
+    const error = await call({ baseUrl: svc.baseUrl }, { domain: 'acme', moduleId: 'acme/billing', version: '1.0.0' }).catch((err: unknown) => err);
+    expect(error).toBeInstanceOf(RegistryYankStateConflictError);
+    expect((error as RegistryYankStateConflictError).verb).toBe(verb);
+  });
+
+  it('never reports a 409 for any OTHER reason as "already yanked" (#1758 re-review R3)', async () => {
+    // The registry answers 409 VERSION_CONFLICT when it gives up after lost optimistic checks: the yank
+    // did NOT happen, and calling it a no-op would tell an operator a compromised release is withdrawn.
+    // A bare generic `conflict` is NOT enough: about twenty engine refusals share that reference.
+    for (const body of [conflictBody('version_conflict'), conflictBody('conflict'), '', 'not json']) {
+      svc = await startServer((req, res) => {
+        res.writeHead(409, { 'content-type': 'application/json' });
+        res.end(body);
+      });
+      const error = await RegistryServerClient.yank({ baseUrl: svc.baseUrl }, { domain: 'acme', moduleId: 'acme/billing', version: '1.0.0' }).catch((err: unknown) => err);
+      expect(error, body).not.toBeInstanceOf(RegistryYankStateConflictError);
+      expect(error, body).toBeInstanceOf(RegistryUnexpectedStatusError);
+      await svc.close();
+      svc = null;
+    }
+  });
+});

package/src/__tests__/registry-transfer-timeouts.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Registry timeouts (#1763): a download is bounded by SILENCE, not by its size, and every timeout is a
+ * typed `RegistryRequestTimeoutError` naming its phase.
+ *
+ * Before: one 10 s signal covered a download's whole body, so an artifact taking longer than that could
+ * never install on any link; and a timeout escaped as a raw `AbortError` (or, mid-JSON, as a "malformed
+ * payload"), so no caller could tell slow from refused.
+ */
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { afterEach, describe, expect, it } from 'vitest';
+import { RegistryRequestTimeoutError, RegistryTimeoutPhase, isRegistryError } from '@wildo-ai/platform-config-lib';
+import { fetchTransfer } from '../services/_http-client';
+import { RegistryServerClient } from '../services/registry-server-client';
+
+let server: Server | undefined;
+
+async function serve(handler: (req: IncomingMessage, res: ServerResponse) => void): Promise<string> {
+  server = createServer(handler);
+  await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve));
+  const address = server.address();
+  if (!address || typeof address === 'string') throw new Error('no address');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+afterEach(async () => {
+  if (!server) return;
+  // Stalled responses are held open on purpose; drop them so close() can return.
+  server.closeAllConnections();
+  await new Promise<void>((resolve) => server!.close(() => resolve()));
+  server = undefined;
+});
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+describe('a download is bounded by silence, not by size (#1763)', () => {
+  it('finishes a transfer that takes far longer than the request budget while bytes keep arriving', async () => {
+    const base = await serve(async (_req, res) => {
+      res.writeHead(200, { 'content-type': 'application/octet-stream' });
+      for (let i = 0; i < 8; i += 1) {
+        res.write(Buffer.from([i]));
+        await sleep(60);
+      }
+      res.end();
+    });
+    const { response, readAll } = await fetchTransfer(`${base}/artifact`, { timeoutMs: 150, idleTimeoutMs: 200 });
+    expect(response.status).toBe(200);
+    // ~480 ms of body against a 150 ms request budget: only an idle budget lets this finish.
+    expect(Array.from(await readAll())).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
+  });
+
+  it('fails a transfer that stalls part-way, as a typed TRANSFER_STALLED timeout', async () => {
+    const base = await serve((_req, res) => {
+      res.writeHead(200, { 'content-type': 'application/octet-stream' });
+      res.write(Buffer.from([1, 2, 3]));
+      // ...and never another byte.
+    });
+    const { readAll } = await fetchTransfer(`${base}/artifact`, { timeoutMs: 500, idleTimeoutMs: 150 });
+    const error = await readAll().catch((err: unknown) => err);
+    expect(error).toBeInstanceOf(RegistryRequestTimeoutError);
+    expect((error as RegistryRequestTimeoutError).phase).toBe(RegistryTimeoutPhase.TRANSFER_STALLED);
+    expect((error as RegistryRequestTimeoutError).timeoutMs).toBe(150);
+  });
+
+  it('fails a registry that never answers, as a typed AWAITING_RESPONSE timeout', async () => {
+    const base = await serve(() => { /* never responds */ });
+    const error = await fetchTransfer(`${base}/artifact`, { timeoutMs: 150 }).catch((err: unknown) => err);
+    expect(error).toBeInstanceOf(RegistryRequestTimeoutError);
+    expect((error as RegistryRequestTimeoutError).phase).toBe(RegistryTimeoutPhase.AWAITING_RESPONSE);
+  });
+});
+
+describe('metadata requests time out in the typed vocabulary (#1763)', () => {
+  it('a resolve that never answers is a typed timeout', async () => {
+    const base = await serve(() => { /* never responds */ });
+    const error = await RegistryServerClient.resolve({ baseUrl: base, timeoutMs: 150 }, { domain: 'd', moduleId: 'acme/x', range: '^1.0.0' }).catch((err: unknown) => err);
+    expect(isRegistryError(error)).toBe(true);
+    expect(error).toBeInstanceOf(RegistryRequestTimeoutError);
+  });
+
+  it('a JSON body cut short by the budget is a TIMEOUT, not a malformed payload', async () => {
+    const base = await serve((_req, res) => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.write('{"version": "1.0');
+      // ...and the rest never arrives.
+    });
+    const error = await RegistryServerClient.resolve({ baseUrl: base, timeoutMs: 200 }, { domain: 'd', moduleId: 'acme/x', range: '^1.0.0' }).catch((err: unknown) => err);
+    expect(error).toBeInstanceOf(RegistryRequestTimeoutError);
+    // The headers arrived, so it is the BODY that ran out, and the budget reported is the caller's own
+    // (#1763 review: it used to say AWAITING_RESPONSE and the 10 s default).
+    expect((error as RegistryRequestTimeoutError).phase).toBe(RegistryTimeoutPhase.READING_BODY);
+    expect((error as RegistryRequestTimeoutError).timeoutMs).toBe(200);
+  });
+});

package/src/services/_http-client.ts

@@ -5,9 +5,12 @@
  * Both clients want the same primitives:
  *   - `joinUrl(base, path)` — single-source-of-truth path joiner
  *     that tolerates leading/trailing slashes;
- *   - `fetchWithTimeout(url, init, timeoutMs)` — abort-on-timeout
- *     wrapper that converts `AbortError`/`TimeoutError` into a
- *     uniform diagnostic message;
+ *   - `fetchWithTimeout(url, init)` — one budget for a metadata
+ *     exchange; an abort becomes a typed `RegistryRequestTimeoutError`;
+ *   - `readJsonBody(...)` — reads that exchange's JSON body, typing a
+ *     body cut short by the same budget as a `READING_BODY` timeout;
+ *   - `fetchTransfer(url, init)` — an artifact download: a response
+ *     budget plus an idle budget between body chunks (#1763);
  *   - `fetchJsonOk(...)` — convenience for liveness probes that
  *     want a boolean answer.
  *
@@ -17,8 +20,17 @@
  * download) extend this file rather than copy the primitives.
  */
 
+import { isAbortLikeError, RegistryRequestTimeoutError, RegistryTimeoutPhase } from '@wildo-ai/platform-config-lib';
+
 const DEFAULT_TIMEOUT_MS = 10_000;
 
+/**
+ * How long a DOWNLOAD may go without receiving a single byte (#1763). An idle budget, not a cap on the
+ * whole body: a large artifact over a slow but moving link finishes, a stalled one fails. 30 s is the
+ * order npm and cargo tolerate before calling a transfer stuck.
+ */
+export const REGISTRY_TRANSFER_IDLE_TIMEOUT_MS = 30_000;
+
 export function joinUrl(base: string, path: string): string {
   const normalized = path.startsWith('/') ? path : `/${path}`;
   return `${base.replace(/\/$/, '')}${normalized}`;
@@ -53,13 +65,95 @@ export async function fetchWithTimeout(
   try {
     return await fetch(url, { ...rest, signal });
   } catch (err) {
-    if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError')) {
-      throw new Error(`${label} request timed out after ${timeoutMs}ms (${url})`);
-    }
+    // Typed, so an `isRegistryError(err)` handler sees it (#1763). The budget spans the whole exchange,
+    // which is right for a small metadata response; a body read the same signal aborts is translated by
+    // the reader (see `readJsonBody`).
+    if (isAbortLikeError(err)) throw new RegistryRequestTimeoutError(url, label, RegistryTimeoutPhase.AWAITING_RESPONSE, timeoutMs);
+    throw err;
+  }
+}
+
+/**
+ * Read a small JSON body fetched through {@link fetchWithTimeout}. A read cut short by that request's
+ * timeout is a TIMEOUT, never a malformed payload (it used to be reported as one).
+ */
+export async function readJsonBody(res: Response, url: string, label: string, timeoutMs: number | undefined): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch (err) {
+    // The headers arrived; the body is what ran out of time (#1763 review).
+    if (isAbortLikeError(err)) throw new RegistryRequestTimeoutError(url, label, RegistryTimeoutPhase.READING_BODY, timeoutMs ?? DEFAULT_TIMEOUT_MS);
     throw err;
   }
 }
 
+export interface TransferInit extends FetchWithTimeoutInit {
+  /** No-bytes budget for the body (default {@link REGISTRY_TRANSFER_IDLE_TIMEOUT_MS}). */
+  idleTimeoutMs?: number;
+}
+
+/**
+ * Fetch for a TRANSFER — an artifact download (#1763). Two budgets, because a metadata timeout cannot
+ * be sized for a body of unknown length:
+ *   - `timeoutMs` bounds the wait for the RESPONSE (status + headers);
+ *   - `idleTimeoutMs` bounds the silence between body chunks, reset on every chunk.
+ * Both aborts surface as `RegistryRequestTimeoutError`, with the phase that fired.
+ */
+export async function fetchTransfer(url: string, init: TransferInit = {}): Promise<{ response: Response; readAll: () => Promise<Uint8Array> }> {
+  const timeoutMs = init.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const idleTimeoutMs = init.idleTimeoutMs ?? REGISTRY_TRANSFER_IDLE_TIMEOUT_MS;
+  const label = init.diagnosticLabel ?? 'HTTP';
+  const { timeoutMs: _t, idleTimeoutMs: _i, diagnosticLabel: _d, ...rest } = init;
+  const controller = new AbortController();
+  let phase = RegistryTimeoutPhase.AWAITING_RESPONSE;
+  let timer = setTimeout(() => controller.abort(), timeoutMs);
+  const timeoutError = () =>
+    new RegistryRequestTimeoutError(url, label, phase, phase === RegistryTimeoutPhase.AWAITING_RESPONSE ? timeoutMs : idleTimeoutMs);
+  let response: Response;
+  try {
+    response = await fetch(url, { ...rest, signal: controller.signal });
+  } catch (err) {
+    clearTimeout(timer);
+    if (isAbortLikeError(err)) throw timeoutError();
+    throw err;
+  }
+  clearTimeout(timer);
+  const readAll = async (): Promise<Uint8Array> => {
+    phase = RegistryTimeoutPhase.TRANSFER_STALLED;
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    const reader = response.body?.getReader();
+    if (!reader) return new Uint8Array(0);
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => controller.abort(), idleTimeoutMs);
+    };
+    arm();
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+        total += value.byteLength;
+        arm();
+      }
+    } catch (err) {
+      if (isAbortLikeError(err) || controller.signal.aborted) throw timeoutError();
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return bytes;
+  };
+  return { response, readAll };
+}
+
 /**
  * Throws on non-2xx; returns the Response otherwise.
  *