@pyric/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/conformance/browser.ts

@@ -0,0 +1,24 @@
+import {
+  CONFORMANCE_SUPPORTS,
+  resolveCanIUse,
+  type BrowserFeatureSupport,
+  type CanIUseOptions,
+} from './.generated/can-i-use-browser.js';
+
+export { createCanIUseTool, type CanIUseToolOptions } from './can-i-use-tool.js';
+export type {
+  Assurance,
+  Availability,
+  BrowserFeatureSupport,
+  CanIUseMatch,
+  CanIUseOptions,
+  CanIUseResult,
+  DeveloperSurface,
+  Fidelity,
+} from './.generated/can-i-use-browser.js';
+
+/** Query the compact browser projection. Full claims and evidence remain on
+ * the Node-only `@pyric/cli/conformance` entry point. */
+export function canIUse(query: string, options?: CanIUseOptions) {
+  return resolveCanIUse<BrowserFeatureSupport>(CONFORMANCE_SUPPORTS, query, options);
+}

package/src/conformance/can-i-use-tool.ts

@@ -0,0 +1,51 @@
+import type { ToolHandler } from '@inbrowser/agent';
+
+interface CanIUseResultLike {
+  match: 'exact' | 'ambiguous' | 'suggestions' | 'none';
+  supports: readonly { summary: string }[];
+}
+
+export interface CanIUseToolOptions<R extends CanIUseResultLike> {
+  description: string;
+  featureDescription: string;
+  importPathDescription: string;
+  query: (feature: string, options: { importPath?: string }) => R;
+}
+
+function resultSummary(result: CanIUseResultLike): string {
+  if (result.match === 'none') return 'No conformance feature matched that query';
+  if (result.match === 'suggestions') return `No exact match; found ${result.supports.length} deterministic suggestions`;
+  if (result.match === 'ambiguous') return `Found ${result.supports.length} exact matches across surfaces`;
+  return result.supports[0]!.summary;
+}
+
+/** The one authored pyric_can_i_use handler shape. Node and browser agents
+ * differ only in the query they pass in, so match semantics, argument
+ * validation, and summaries cannot drift between surfaces. */
+export function createCanIUseTool<R extends CanIUseResultLike>(options: CanIUseToolOptions<R>): ToolHandler {
+  return {
+    name: 'pyric_can_i_use',
+    description: options.description,
+    parameters: {
+      type: 'object',
+      properties: {
+        feature: { type: 'string', description: options.featureDescription },
+        importPath: { type: 'string', description: options.importPathDescription },
+      },
+      required: ['feature'],
+    },
+    async execute(args) {
+      const { feature, importPath } = args as { feature?: unknown; importPath?: unknown };
+      if (typeof feature !== 'string' || feature.trim() === '') {
+        return { ok: false, summary: 'pyric_can_i_use requires a non-empty feature name' };
+      }
+      if (importPath !== undefined && (typeof importPath !== 'string' || importPath.trim() === '')) {
+        return { ok: false, summary: 'pyric_can_i_use importPath must be a non-empty string when provided' };
+      }
+      const result = options.query(feature, {
+        importPath: typeof importPath === 'string' ? importPath : undefined,
+      });
+      return { ok: result.match === 'exact', summary: resultSummary(result), data: result };
+    },
+  };
+}

package/src/conformance/can-i-use.ts

@@ -0,0 +1,18 @@
+import {
+  CONFORMANCE_IMPORT_EVIDENCE,
+  CONFORMANCE_SUPPORTS,
+  resolveCanIUse,
+  resolveImportEvidence,
+  type CanIUseOptions,
+  type FeatureSupport,
+} from './.generated/can-i-use.js';
+
+/** Query the generated, build-time conformance support projection. */
+export function canIUse(query: string, options?: CanIUseOptions) {
+  return resolveCanIUse<FeatureSupport>(CONFORMANCE_SUPPORTS, query, options);
+}
+
+/** Find the generated compatibility-page evidence for a published import. */
+export function canIUseImport(importPath: string) {
+  return resolveImportEvidence(CONFORMANCE_IMPORT_EVIDENCE, importPath);
+}

package/src/conformance/docs.ts

@@ -0,0 +1,8 @@
+/** The docs projection: every conformance page (per-service compatibility
+ * matrices plus the public API coverage scoreboard) fully rendered at package
+ * build from the central conformance model. Consumers display these pages —
+ * the docs site is one such consumer — they never re-derive the model. */
+export {
+  CONFORMANCE_DOCS_PAGES,
+  type ConformanceDocsPage,
+} from './.generated/conformance-docs.js';

package/src/conformance/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Query Pyric's build-time conformance model by developer-facing feature name.
+ * Results keep availability, behavior fidelity, and assurance eligibility as
+ * separate trust axes.
+ */
+export {
+  type Assurance,
+  type Availability,
+  type DeveloperSurface,
+  type FeatureClaim,
+  type FeatureClaimKind,
+  type FeatureSupport,
+  type Fidelity,
+  type ImportEvidence,
+  type CanIUseMatch,
+  type CanIUseOptions,
+  type CanIUseResult,
+} from './.generated/can-i-use.js';
+
+export { canIUse, canIUseImport } from './can-i-use.js';

package/src/conformance/tools.ts

@@ -0,0 +1,16 @@
+import type { ToolHandler } from '@inbrowser/agent';
+import { createCanIUseTool } from './can-i-use-tool.js';
+import { CONFORMANCE_SUPPORTS, resolveCanIUse, type FeatureSupport } from './.generated/can-i-use.js';
+
+/** Node-only conformance tools. The richer model never enters a browser bundle. */
+export function createConformanceTools(): ToolHandler[] {
+  return [
+    createCanIUseTool({
+      description:
+        'Check whether Pyric can support a developer-facing Firebase feature. Reports availability, behavior fidelity, and assurance eligibility separately, with caveats and auditable claims. Exact names resolve first; fuzzy names return deterministic candidates.',
+      featureDescription: 'Developer feature name, optionally prefixed by a surface (for example firestore-rules/getAfter).',
+      importPathDescription: 'Optional published import path that must expose the feature (for example pyric/storage).',
+      query: (feature, options) => resolveCanIUse<FeatureSupport>(CONFORMANCE_SUPPORTS, feature, options),
+    }),
+  ];
+}

package/src/credentials/core/memoize-ttl.ts

@@ -0,0 +1,142 @@
+/**
+ * Host-side caching wrapper for credential resolvers.
+ *
+ * Per F4, the SDK convention is "resolvers fire per-dispatch; hosts
+ * memoize via `memoizeTtl` if cost matters." This is that memoizer.
+ *
+ * Default behavior (locked in v4.1):
+ * - Parse `expires_in` from the resolved token's claims when the
+ *   resolver returns an object whose shape carries it.
+ * - Refresh proactively at **90% of TTL** — gives the next caller a
+ *   fresh token before the in-flight window hits expiry.
+ * - Accept an explicit `ttlMs` override when the resolver doesn't
+ *   surface `expires_in` (rare; tests, mock tokens).
+ *
+ * Two shapes supported:
+ *
+ * 1. **Plain string resolver** — `() => Promise<string>`. Caller
+ *    must supply `ttlMs` (the SDK can't infer TTL from an opaque
+ *    string).
+ * 2. **Structured token resolver** — `() => Promise<{ token: string;
+ *    expiresIn?: number }>`. `expiresIn` is parsed as seconds; the
+ *    memoizer refreshes at 90% of that. Callers can still pass
+ *    `ttlMs` to override.
+ */
+
+interface MemoizedEntry {
+  value: string;
+  /** Epoch ms when this entry should be refreshed (not when it
+   *  expires — the 90% point). */
+  refreshAt: number;
+}
+
+export interface MemoizeTtlOptions {
+  /** Explicit TTL in milliseconds. Required for plain-string
+   *  resolvers; optional override for structured-token resolvers
+   *  (defaults to 90% of `expiresIn`). */
+  ttlMs?: number;
+  /** Fraction of TTL to use as the refresh window. Default 0.9. */
+  refreshAtFraction?: number;
+  /**
+   * Per-attempt timeout (ms) on the underlying resolver. Default
+   * 30_000 (30 seconds). If the resolver hangs longer than this,
+   * the in-flight wait rejects with a timeout error and the next
+   * caller can retry afresh — prevents a wedged resolver from
+   * deadlocking every subsequent call.
+   */
+  resolverTimeoutMs?: number;
+}
+
+/**
+ * Wrap a plain string-returning resolver with TTL memoization.
+ * Callers must supply `ttlMs` since opaque strings carry no
+ * expiry information.
+ */
+export function memoizeTtl(
+  resolver: () => Promise<string>,
+  opts: MemoizeTtlOptions & { ttlMs: number },
+): () => Promise<string>;
+
+/**
+ * Wrap a structured-token resolver with TTL memoization. The
+ * memoizer parses `expiresIn` (seconds) from the resolver's return
+ * value and refreshes at 90% of TTL by default.
+ */
+export function memoizeTtl(
+  resolver: () => Promise<{ token: string; expiresIn?: number }>,
+  opts?: MemoizeTtlOptions,
+): () => Promise<string>;
+
+export function memoizeTtl(
+  resolver:
+    | (() => Promise<string>)
+    | (() => Promise<{ token: string; expiresIn?: number }>),
+  opts: MemoizeTtlOptions = {},
+): () => Promise<string> {
+  let entry: MemoizedEntry | null = null;
+  let inFlight: Promise<string> | null = null;
+  const fraction = opts.refreshAtFraction ?? 0.9;
+  const timeoutMs = opts.resolverTimeoutMs ?? 30_000;
+
+  return async () => {
+    const now = Date.now();
+    if (entry && entry.refreshAt > now) return entry.value;
+    // Coalesce concurrent refreshes — only one inflight at a time.
+    if (inFlight) return inFlight;
+
+    inFlight = (async () => {
+      // Race the resolver against a timeout so a hung resolver
+      // can't wedge every subsequent caller. The timer is cleared
+      // either way so we don't keep the process alive.
+      let timerHandle: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<never>((_, reject) => {
+        timerHandle = setTimeout(() => {
+          reject(
+            new Error(
+              `memoizeTtl: resolver did not complete within ${timeoutMs}ms`,
+            ),
+          );
+        }, timeoutMs);
+      });
+      let raw: string | { token: string; expiresIn?: number };
+      try {
+        raw = await Promise.race([resolver(), timeout]);
+      } finally {
+        if (timerHandle !== undefined) clearTimeout(timerHandle);
+      }
+
+      let token: string;
+      let ttlMs: number;
+      if (typeof raw === 'string') {
+        token = raw;
+        if (opts.ttlMs === undefined) {
+          throw new Error(
+            'memoizeTtl: plain-string resolver requires explicit ttlMs',
+          );
+        }
+        ttlMs = opts.ttlMs;
+      } else {
+        token = raw.token;
+        ttlMs =
+          opts.ttlMs ??
+          (raw.expiresIn !== undefined
+            ? raw.expiresIn * 1000
+            : (() => {
+                throw new Error(
+                  'memoizeTtl: structured-token resolver returned no expiresIn; pass an explicit ttlMs',
+                );
+              })());
+      }
+      entry = {
+        value: token,
+        refreshAt: Date.now() + Math.floor(ttlMs * fraction),
+      };
+      return token;
+    })();
+    try {
+      return await inFlight;
+    } finally {
+      inFlight = null;
+    }
+  };
+}

package/src/credentials/core/types.ts

@@ -0,0 +1,10 @@
+/**
+ * Project identity plus a fresh-enough Google OAuth token resolver.
+ *
+ * The identity is stable for the lifetime of an operation while token
+ * acquisition remains lazy so long-running commands can refresh credentials.
+ */
+export interface ProjectScope {
+  readonly projectId: string;
+  resolveToken(): Promise<string>;
+}

package/src/credentials/node/from-adc.ts

@@ -0,0 +1,96 @@
+/**
+ * Application Default Credentials source — the gcloud / workload-identity path,
+ * the modern keyless alternative to a long-lived token. Reads the well-known ADC
+ * file (`gcloud auth application-default login`):
+ *   - `authorized_user` -> refresh-token grant (the common dev case).
+ *   - `service_account` -> delegate to `fromServiceAccount`.
+ * The metadata-server path (GCE / Cloud Run) is a separate fallback, not yet
+ * wired. Node-only (reads disk) -> lives in node/.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { ProjectScope } from '../core/types.js';
+import { memoizeTtl } from '../core/memoize-ttl.js';
+import { fromServiceAccount } from './from-service-account.js';
+
+const GOOGLE_TOKEN_URI = 'https://oauth2.googleapis.com/token';
+
+/** The well-known ADC file path (honours CLOUDSDK_CONFIG; %APPDATA% on Windows). */
+export function adcWellKnownPath(env: NodeJS.ProcessEnv = process.env): string {
+  const base =
+    env.CLOUDSDK_CONFIG ??
+    (process.platform === 'win32' && env.APPDATA ? join(env.APPDATA, 'gcloud') : join(homedir(), '.config', 'gcloud'));
+  return join(base, 'application_default_credentials.json');
+}
+
+/**
+ * Build a `ProjectScope` from ADC, or `null` if no ADC file is present. The
+ * project is supplied by the caller — an ADC user credential isn't bound to one
+ * (`--project` / `.firebaserc`).
+ */
+export async function fromAdc(
+  projectId: string,
+  env: NodeJS.ProcessEnv = process.env,
+  path: string = adcWellKnownPath(env),
+): Promise<ProjectScope | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf-8');
+  } catch {
+    return null; // no ADC file
+  }
+  let parsed: { type?: string; client_id?: string; client_secret?: string; refresh_token?: string };
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (parsed.type === 'authorized_user' && parsed.client_id && parsed.client_secret && parsed.refresh_token) {
+    const clientId = parsed.client_id;
+    const clientSecret = parsed.client_secret;
+    const refreshToken = parsed.refresh_token;
+    const resolveToken = memoizeTtl(async () => {
+      const { access_token, expires_in } = await exchangeAdcRefreshToken(
+        clientId,
+        clientSecret,
+        refreshToken,
+      );
+      return { token: access_token, expiresIn: expires_in };
+    });
+    return Object.freeze({ projectId, resolveToken });
+  }
+
+  if (parsed.type === 'service_account') {
+    const sa = await fromServiceAccount(raw); // fromServiceAccount accepts a raw JSON string
+    return projectId && projectId !== sa.projectId
+      ? Object.freeze({ projectId, resolveToken: sa.resolveToken })
+      : sa;
+  }
+
+  return null; // unknown ADC type (e.g. external_account) — not supported here
+}
+
+async function exchangeAdcRefreshToken(
+  clientId: string,
+  clientSecret: string,
+  refreshToken: string,
+): Promise<{ access_token: string; expires_in: number }> {
+  const response = await fetch(GOOGLE_TOKEN_URI, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: clientId,
+      client_secret: clientSecret,
+      refresh_token: refreshToken,
+      grant_type: 'refresh_token',
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `pyric: Application Default Credentials token exchange failed (${response.status}): ${await response.text()}`,
+    );
+  }
+  return (await response.json()) as { access_token: string; expires_in: number };
+}

package/src/credentials/node/from-service-account.ts

@@ -0,0 +1,133 @@
+/**
+ * Build a `ProjectScope` from a Google service
+ * account JSON file. Exchanges the SA key for a short-lived OAuth
+ * access token via the standard JWT-bearer flow, and wires
+ * `memoizeTtl` internally so consumers get caching for free.
+ *
+ * No `firebase-admin` dependency — uses only Node's built-in
+ * `crypto` for RS256 signing and `fetch` for the token exchange.
+ *
+ * **Node-only credential adapter**: the function itself requires
+ * `node:fs/promises` + `node:crypto`.
+ */
+
+import { memoizeTtl } from '../core/memoize-ttl.js';
+import type { ProjectScope } from '../core/types.js';
+
+const GOOGLE_TOKEN_URI = 'https://oauth2.googleapis.com/token';
+const SCOPE = [
+  // Project verification and inspection use Firebase and Google Cloud APIs.
+  'https://www.googleapis.com/auth/firebase',
+  'https://www.googleapis.com/auth/cloud-platform',
+].join(' ');
+
+interface ServiceAccount {
+  client_email: string;
+  private_key: string;
+  project_id: string;
+  token_uri?: string;
+}
+
+interface TokenResponse {
+  access_token: string;
+  expires_in: number;
+  token_type: string;
+}
+
+/**
+ * Read the service account from a JSON file and return a
+ * `ProjectScope` whose `resolveToken` is memoized internally.
+ *
+ * The JSON file path can be:
+ * - An absolute / relative filesystem path (Node only).
+ * - A base64-encoded JSON string (when prefixed with `base64:`),
+ *   for environments that ship the SA in an env var.
+ */
+export async function fromServiceAccount(
+  saJsonOrPath: string,
+): Promise<ProjectScope> {
+  const sa = await loadServiceAccount(saJsonOrPath);
+  const resolveToken = memoizeTtl(async () => {
+    const { access_token, expires_in } = await exchangeJwtForAccessToken(sa);
+    return { token: access_token, expiresIn: expires_in };
+  });
+  // Freeze the returned scope so `projectId` can't be mutated at
+  // runtime. TS `readonly` is compile-time-only; Object.freeze
+  // enforces it at runtime — defense in depth for the
+  // security-relevant identity field.
+  return Object.freeze({
+    projectId: sa.project_id,
+    resolveToken,
+  });
+}
+
+async function loadServiceAccount(saJsonOrPath: string): Promise<ServiceAccount> {
+  let raw: string;
+  if (saJsonOrPath.startsWith('base64:')) {
+    raw = Buffer.from(saJsonOrPath.slice('base64:'.length), 'base64').toString('utf-8');
+  } else if (saJsonOrPath.trim().startsWith('{')) {
+    raw = saJsonOrPath;
+  } else {
+    // Dynamic import keeps `node:fs/promises` out of browser bundles
+    // when this function isn't called.
+    const { readFile } = await import('node:fs/promises');
+    raw = await readFile(saJsonOrPath, 'utf-8');
+  }
+  const parsed = JSON.parse(raw) as Partial<ServiceAccount>;
+  if (!parsed.client_email || !parsed.private_key || !parsed.project_id) {
+    throw new Error(
+      'fromServiceAccount: input is missing required fields (client_email, private_key, project_id)',
+    );
+  }
+  return parsed as ServiceAccount;
+}
+
+async function exchangeJwtForAccessToken(sa: ServiceAccount): Promise<TokenResponse> {
+  const jwt = await buildSignedJwt(sa);
+  const res = await fetch(sa.token_uri ?? GOOGLE_TOKEN_URI, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+      assertion: jwt,
+    }).toString(),
+  });
+  if (!res.ok) {
+    throw new Error(
+      `fromServiceAccount: token exchange failed (${res.status}): ${await res.text()}`,
+    );
+  }
+  return (await res.json()) as TokenResponse;
+}
+
+async function buildSignedJwt(sa: ServiceAccount): Promise<string> {
+  // Dynamic import keeps `node:crypto` out of browser bundles when
+  // `fromServiceAccount` is never called.
+  const { createSign } = await import('node:crypto');
+  const now = Math.floor(Date.now() / 1000);
+  const header = { alg: 'RS256', typ: 'JWT' };
+  const claims = {
+    iss: sa.client_email,
+    scope: SCOPE,
+    aud: sa.token_uri ?? GOOGLE_TOKEN_URI,
+    exp: now + 3600,
+    iat: now,
+  };
+  const headerB64 = base64UrlEncode(JSON.stringify(header));
+  const claimsB64 = base64UrlEncode(JSON.stringify(claims));
+  const signingInput = `${headerB64}.${claimsB64}`;
+  const signer = createSign('RSA-SHA256');
+  signer.update(signingInput);
+  signer.end();
+  const signature = signer.sign(sa.private_key);
+  const signatureB64 = base64UrlEncodeBuffer(signature);
+  return `${signingInput}.${signatureB64}`;
+}
+
+function base64UrlEncode(s: string): string {
+  return base64UrlEncodeBuffer(Buffer.from(s, 'utf-8'));
+}
+
+function base64UrlEncodeBuffer(b: Buffer): string {
+  return b.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}

package/src/credentials/node/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Node-only credentials used by hosted Rules Test API verification.
+ * Pyric does not own an interactive Google login or credential store.
+ */
+export { fromAdc } from './from-adc.js';
+export { fromServiceAccount } from './from-service-account.js';

package/src/discover/concurrency.ts

@@ -0,0 +1,127 @@
+/**
+ * Bounded concurrency primitives for the Firestore discover_paths crawler.
+ *
+ * Phase 0.3 of the validation plan locked layered BFS with `Promise.all`-per-
+ * layer as the production strategy (38× faster than serial DFS on the
+ * representative corpus). This module provides the two pieces every layer
+ * needs:
+ *
+ *   - `Semaphore` — FIFO-ordered counting semaphore with `acquire`/`release`.
+ *   - `runWithLimit` — ergonomic wrapper that maps a list of async producers
+ *     through the semaphore and resolves to the ordered results.
+ *
+ * Kept self-contained so the `firestore/discover` subsystem owns its own
+ * concurrency contract.
+ */
+'use strict';
+
+/**
+ * FIFO counting semaphore. `acquire()` resolves immediately while
+ * fewer than `max` permits are checked out, otherwise it queues until
+ * a `release()` frees a slot. Waiters are served in arrival order.
+ *
+ * `release()` without a prior `acquire()` is a no-op (does not go
+ * negative). This is intentional — it lets defensive `try/finally`
+ * release in error paths without bookkeeping.
+ */
+export class Semaphore {
+  private readonly max: number;
+  private active = 0;
+  private queue: Array<() => void> = [];
+
+  constructor(max: number) {
+    if (!Number.isInteger(max) || max < 1) {
+      throw new RangeError(
+        `Semaphore: max must be a positive integer, got ${max}`,
+      );
+    }
+    this.max = max;
+  }
+
+  async acquire(): Promise<void> {
+    if (this.active < this.max) {
+      this.active++;
+      return;
+    }
+    return new Promise<void>((resolve) => {
+      this.queue.push(() => {
+        this.active++;
+        resolve();
+      });
+    });
+  }
+
+  release(): void {
+    if (this.active === 0) return; // never go negative
+    this.active--;
+    const next = this.queue.shift();
+    if (next) next();
+  }
+
+  /**
+   * Number of permits currently checked out. For tests and instrumentation
+   * only; do not branch on this in production logic.
+   */
+  get inFlight(): number {
+    return this.active;
+  }
+
+  /**
+   * Number of waiters queued. For tests and instrumentation only.
+   */
+  get pending(): number {
+    return this.queue.length;
+  }
+}
+
+/**
+ * Run `items` through `producer` concurrently, capping in-flight calls
+ * at `limit`. Returns results in input order (same shape as
+ * `Promise.all(items.map(producer))` — but bounded).
+ *
+ * `producer` may throw; the rejection propagates after in-flight work
+ * settles. Other items continue running so the rejection isn't masked
+ * by a Promise.all-style fast-fail leaving zombie pending work.
+ *
+ * Implementation detail: uses an internal `Semaphore(limit)`; callers
+ * who need to share a permit pool across multiple `runWithLimit` calls
+ * (e.g. crawler global RPC cap) should use the `Semaphore` class
+ * directly via `acquire`/`release`.
+ */
+export async function runWithLimit<T, R>(
+  items: readonly T[],
+  limit: number,
+  producer: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new RangeError(
+      `runWithLimit: limit must be a positive integer, got ${limit}`,
+    );
+  }
+  if (items.length === 0) return [];
+
+  const sem = new Semaphore(limit);
+  const results: R[] = new Array<R>(items.length);
+  const errors: { index: number; error: unknown }[] = [];
+
+  await Promise.all(
+    items.map(async (item, index) => {
+      await sem.acquire();
+      try {
+        results[index] = await producer(item, index);
+      } catch (error) {
+        errors.push({ index, error });
+      } finally {
+        sem.release();
+      }
+    }),
+  );
+
+  if (errors.length > 0) {
+    // Surface the first error in input order — agents/tests can rely on
+    // a deterministic surface even when multiple producers throw.
+    errors.sort((a, b) => a.index - b.index);
+    throw errors[0]!.error;
+  }
+  return results;
+}