v0.2.24: sync from monorepo 2026-07-02

Author: azeth-sync[bot]

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azeth/sdk",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "type": "module",
   "description": "TypeScript SDK for the Azeth trust infrastructure — smart accounts, x402 payments, reputation, and service discovery",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "test:mutation": "npx stryker run"
   },
   "dependencies": {
-    "@azeth/common": "^0.2.23",
+    "@azeth/common": "^0.2.24",
     "@x402/core": "^2.14.0",
     "@x402/extensions": "^2.14.0",
     "@xmtp/agent-sdk": "^2.2.0",

src/payments/smart-fetch.ts

@@ -145,11 +145,27 @@ export async function smartFetch402(
     sortByReputation: true,
     minReputation: options?.minReputation,
     entityType: options?.entityType,
-    limit: maxRetries * 3,
+    // R4-3: the usable-endpoint filter below runs AFTER this fetch, and registries carry
+    // many entries with blank/placeholder/tunnel endpoints — a small fetch window can cut
+    // off every usable provider before the filter sees it. Fetch a wide window (one cheap
+    // indexed query) and only then narrow to maxRetries attempts.
+    limit: Math.min(Math.max(maxRetries * 3, 50), 100),
   };
 
   const resolvedChain = chainName ?? chainIdToName(publicClient.chain?.id ?? 0) ?? 'baseSepolia' as SupportedChainName;
   const discoveryResult = await discoverServicesWithFallback(serverUrl, discoveryParams, publicClient, resolvedChain);
+
+  // R4-2: a reputation floor is a TRUST decision — it must fail closed. The on-chain
+  // discovery fallback cannot verify reputation (minReputationIgnored), so candidates from
+  // that path are unvetted against the caller's threshold and must not be paid.
+  if (options?.minReputation !== undefined && discoveryResult.minReputationIgnored) {
+    throw new AzethError(
+      `Cannot verify the minReputation=${options.minReputation} floor: the reputation-indexed discovery service is unavailable and on-chain fallback discovery cannot rank by reputation. Retry without minReputation, or retry later.`,
+      'SERVICE_NOT_FOUND',
+      { capability, minReputation: options.minReputation, reason: 'REPUTATION_FLOOR_UNVERIFIABLE' },
+    );
+  }
+
   const services = discoveryResult.entries
     // Reject empty AND whitespace-only endpoints — registry entries with " "
     // are truthy but produce `fetch(" ")` → "Invalid URL", aborting the fallback (S-3).
@@ -158,7 +174,9 @@ export async function smartFetch402(
 
   if (services.length === 0) {
     throw new AzethError(
-      `No services found for capability "${capability}"`,
+      options?.minReputation !== undefined
+        ? `No services with a usable endpoint meet minReputation=${options.minReputation} for capability "${capability}"`
+        : `No services found for capability "${capability}"`,
       'SERVICE_NOT_FOUND',
       { capability, minReputation: options?.minReputation },
     );
@@ -375,10 +393,20 @@ export async function smartFetch402(
   // All services failed — or, when an intent was given, it couldn't be resolved against any
   // provider's catalog. In the latter case we attach the menu (`options`) so the agent can
   // refine its intent/params and retry in ONE free round-trip instead of hitting a dead end. (F6)
+  // R4-4: the per-service causes are inlined into the MESSAGE (not only `details`, which
+  // some presentation layers drop) so "all failed" is never the whole story the agent sees.
+  const failureSummary = failedServices
+    .filter(f => !f.error.startsWith('intent unresolved') && !f.error.startsWith('catalog returned'))
+    .slice(0, 3)
+    .map(f => `${f.service.name}: ${f.error}`)
+    .join('; ');
+  const catalogMsg = hasIntent
+    ? `Could not resolve your intent for capability "${capability}". See "options" for the available catalog entries and their valid params, then retry with matching intent/params.`
+    : `Providers for capability "${capability}" serve a catalog of priced routes — pass "intent" or "params" to select one. See "options" for the catalog entries and their valid params.`;
   throw new AzethError(
     catalogOptions.length > 0
-      ? `Could not resolve your intent for capability "${capability}". See "options" for the available catalog entries and their valid params, then retry with matching intent/params.`
-      : `All ${services.length} services for capability "${capability}" failed`,
+      ? failureSummary ? `${catalogMsg} Other attempted service(s) failed — ${failureSummary}` : catalogMsg
+      : `All ${services.length} service(s) for capability "${capability}" failed — ${failureSummary}`,
     'SERVICE_NOT_FOUND',
     {
       capability,

src/registry/discover.ts

@@ -243,7 +243,10 @@ async function discoverServicesWithFallbackInner(
     const entries = await discoverServices(serverUrl, params);
     // Fall back to on-chain when server returns empty results — the server index may be
     // stale or incomplete, but the on-chain registry is the source of truth.
-    if (entries.length > 0) {
+    // EXCEPTION (R4-2): when a minReputation floor was requested, an empty-but-successful
+    // server answer is AUTHORITATIVE ("no service meets the threshold") — the on-chain
+    // fallback cannot verify reputation and would reintroduce unfiltered candidates.
+    if (entries.length > 0 || params.minReputation !== undefined) {
       return { entries, source: 'server' };
     }
   } catch (err: unknown) {

test/payments/smart-fetch.test.ts

@@ -85,11 +85,13 @@ describe('smartFetch402 (standalone routing layer)', () => {
     expect(result.paymentMade).toBe(true);
     expect(result.failedServices).toBeUndefined();
 
-    // Verify discovery was called with sortByReputation
+    // Verify discovery was called with sortByReputation and a WIDE fetch window (R4-3:
+    // the usable-endpoint filter runs after this fetch, so a narrow window can cut off
+    // every usable provider among blank/tunnel-endpoint registrations)
     expect(mockedDiscover).toHaveBeenCalledWith(SERVER_URL, expect.objectContaining({
       capability: 'price-feed',
       sortByReputation: true,
-      limit: 9,
+      limit: 50,
     }), expect.anything(), expect.anything());
   });
 
@@ -188,10 +190,38 @@ describe('smartFetch402 (standalone routing layer)', () => {
     );
 
     expect(mockedDiscover).toHaveBeenCalledWith(SERVER_URL, expect.objectContaining({
-      limit: 15,
+      limit: 50, // floor of 50 dominates maxRetries*3 (R4-3)
     }), expect.anything(), expect.anything());
   });
 
+  it('fails closed when a minReputation floor cannot be verified (on-chain fallback, R4-2)', async () => {
+    const unvetted = makeService({ tokenId: 1550n, name: 'ZeroRepCatalog', reputation: 0 });
+    mockedDiscover.mockResolvedValueOnce({ entries: [unvetted], source: 'on-chain', minReputationIgnored: true });
+
+    await expect(
+      smartFetch402(
+        publicClient as any, walletClient as any, TEST_OWNER, SERVER_URL,
+        'price-feed', { minReputation: 90 },
+      ),
+    ).rejects.toThrow(/Cannot verify the minReputation=90 floor/);
+
+    // The unvetted candidate must never be paid or even fetched
+    expect(mockedFetch402).not.toHaveBeenCalled();
+  });
+
+  it('inlines per-service failure causes into the all-failed error message (R4-4)', async () => {
+    const service = makeService({ name: 'BrokeService' });
+    mockedDiscover.mockResolvedValueOnce({ entries: [service], source: 'server' });
+    mockedFetch402.mockRejectedValueOnce(new AzethError('Insufficient USDC balance: have 0, need 0.01', 'INSUFFICIENT_BALANCE'));
+
+    await expect(
+      smartFetch402(
+        publicClient as any, walletClient as any, TEST_OWNER, SERVER_URL,
+        'price-feed',
+      ),
+    ).rejects.toThrow(/BrokeService: Insufficient USDC balance/);
+  });
+
   it('should pre-filter services without an endpoint', async () => {
     const noEndpoint = makeService({ tokenId: 1n, name: 'NoEndpoint', endpoint: undefined });
     const withEndpoint = makeService({ tokenId: 2n, name: 'HasEndpoint', endpoint: 'https://good.test-svc.io' });

test/registry/discover.test.ts

@@ -173,6 +173,22 @@ describe('registry/discover', () => {
       expect(result.entries).toEqual(mockEntries);
     });
 
+    it('treats an empty server result as authoritative when minReputation is set (R4-2)', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(200, { data: [] }));
+      const publicClient = createMockPublicClient();
+
+      const result = await discoverServicesWithFallback(
+        serverUrl, { capability: 'data', minReputation: 90 }, publicClient, 'baseSepolia',
+      );
+
+      // "No service meets the threshold" IS the answer — the on-chain fallback cannot
+      // verify reputation and would reintroduce unvetted candidates.
+      expect(result.source).toBe('server');
+      expect(result.entries).toEqual([]);
+      expect(result.minReputationIgnored).toBeUndefined();
+      expect(publicClient.readContract).not.toHaveBeenCalled();
+    });
+
     /** Helper: build a RegistrySnapshot tuple for oracle mock responses */
     function makeSnapshot(
       tokenId: bigint,