@aztec/foundation 0.0.1-commit.9b94fc1 → 0.0.1-commit.b468ad8

package/src/curves/bn254/point.ts

@@ -0,0 +1,170 @@
+import {
+  BN254_G1_GENERATOR,
+  BN254_G2_GENERATOR,
+  BarretenbergSync,
+  type Bn254G1Point as BbApiBn254G1Point,
+  type Bn254G2Point as BbApiBn254G2Point,
+} from '@aztec/bb.js';
+
+import { Fq, Fr } from './field.js';
+
+/**
+ * BN254 G1 point using foundation field classes.
+ * Represents a point on the BN254 elliptic curve in affine coordinates.
+ */
+export class Bn254G1Point {
+  constructor(
+    public readonly x: Fq,
+    public readonly y: Fq,
+  ) {}
+
+  private toBbApiPoint(): BbApiBn254G1Point {
+    return {
+      x: this.x.toBuffer(),
+      y: this.y.toBuffer(),
+    };
+  }
+
+  private static fromBbApiPoint(point: BbApiBn254G1Point): Bn254G1Point {
+    return new Bn254G1Point(Fq.fromBuffer(Buffer.from(point.x)), Fq.fromBuffer(Buffer.from(point.y)));
+  }
+
+  async isOnCurve(): Promise<boolean> {
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+
+    const apiPoint = this.toBbApiPoint();
+    const response = api.bn254G1IsOnCurve({ point: apiPoint });
+    return response.isOnCurve;
+  }
+
+  /**
+   * Get the generator point for BN254 G1, or perform scalar multiplication.
+   * When called without arguments, returns the base generator point.
+   * When called with a scalar, returns scalar * generator (useful for public key derivation).
+   */
+  static async generator(scalar?: Fr): Promise<Bn254G1Point> {
+    if (!scalar) {
+      return new Bn254G1Point(
+        Fq.fromBuffer(Buffer.from(BN254_G1_GENERATOR.x)),
+        Fq.fromBuffer(Buffer.from(BN254_G1_GENERATOR.y)),
+      );
+    }
+
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+
+    const response = api.bn254G1Mul({
+      point: BN254_G1_GENERATOR,
+      scalar: scalar.toBuffer(),
+    });
+
+    return Bn254G1Point.fromBbApiPoint(response.point);
+  }
+
+  /**
+   * Decompress a BN254 G1 point from compressed form (32 bytes).
+   * The compressed format encodes the x-coordinate and the sign bit of the y-coordinate
+   * in the most significant bit.
+   */
+  static async fromCompressed(compressed: Buffer): Promise<Bn254G1Point> {
+    if (compressed.length !== 32) {
+      throw new Error('Invalid compressed point length');
+    }
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+
+    const response = api.bn254G1FromCompressed({
+      compressed: new Uint8Array(compressed),
+    });
+
+    return Bn254G1Point.fromBbApiPoint(response.point);
+  }
+
+  /**
+   * Compress this BN254 G1 point to 32 bytes.
+   * The compressed format encodes the x-coordinate and the sign bit of the y-coordinate
+   * in the most significant bit (bit 255).
+   */
+  compress(): Buffer {
+    const xBytes = this.x.toBuffer();
+    // Get the least significant bit of y to determine the sign
+    const yLsb = this.y.toBigInt() & 1n;
+    // If y is odd, set the most significant bit (bit 255) of the output
+    if (yLsb === 1n) {
+      xBytes[0] |= 0x80;
+    }
+    return xBytes;
+  }
+
+  equals(other: Bn254G1Point): boolean {
+    return this.x.equals(other.x) && this.y.equals(other.y);
+  }
+
+  toString(): string {
+    return `Bn254G1Point(x: ${this.x.toString()}, y: ${this.y.toString()})`;
+  }
+}
+
+/**
+ * BN254 G2 point using foundation field classes.
+ * Represents a point on the BN254 G2 curve (twist curve) in affine coordinates.
+ * G2 points use extension field coordinates (Fq2).
+ */
+export class Bn254G2Point {
+  constructor(
+    public readonly x: [Fq, Fq],
+    public readonly y: [Fq, Fq],
+  ) {}
+
+  private toBbApiPoint(): BbApiBn254G2Point {
+    return {
+      x: [this.x[0].toBuffer(), this.x[1].toBuffer()],
+      y: [this.y[0].toBuffer(), this.y[1].toBuffer()],
+    };
+  }
+
+  private static fromBbApiPoint(point: BbApiBn254G2Point): Bn254G2Point {
+    return new Bn254G2Point(
+      [Fq.fromBuffer(Buffer.from(point.x[0])), Fq.fromBuffer(Buffer.from(point.x[1]))],
+      [Fq.fromBuffer(Buffer.from(point.y[0])), Fq.fromBuffer(Buffer.from(point.y[1]))],
+    );
+  }
+
+  /**
+   * Get the generator point for BN254 G2, or perform scalar multiplication.
+   * When called without arguments, returns the base generator point.
+   * When called with a scalar, returns scalar * generator.
+   */
+  static async generator(scalar?: Fr): Promise<Bn254G2Point> {
+    if (!scalar) {
+      return new Bn254G2Point(
+        [Fq.fromBuffer(Buffer.from(BN254_G2_GENERATOR.x[0])), Fq.fromBuffer(Buffer.from(BN254_G2_GENERATOR.x[1]))],
+        [Fq.fromBuffer(Buffer.from(BN254_G2_GENERATOR.y[0])), Fq.fromBuffer(Buffer.from(BN254_G2_GENERATOR.y[1]))],
+      );
+    }
+
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+
+    const response = api.bn254G2Mul({
+      point: BN254_G2_GENERATOR as BbApiBn254G2Point,
+      scalar: scalar.toBuffer(),
+    });
+
+    return Bn254G2Point.fromBbApiPoint(response.point);
+  }
+
+  equals(other: Bn254G2Point): boolean {
+    return (
+      this.x[0].equals(other.x[0]) &&
+      this.x[1].equals(other.x[1]) &&
+      this.y[0].equals(other.y[0]) &&
+      this.y[1].equals(other.y[1])
+    );
+  }
+
+  toString(): string {
+    return `Bn254G2Point(x: (${this.x[0].toString()}, ${this.x[1].toString()}), y: (${this.y[0].toString()}, ${this.y[1].toString()}))`;
+  }
+}

package/src/curves/grumpkin/index.ts

@@ -0,0 +1,11 @@
+import { Fq } from '../bn254/field.js';
+
+export * from './point.js';
+
+/**
+ * GrumpkinScalar is an Fq.
+ * @remarks Called GrumpkinScalar because it is used to represent elements in Grumpkin's scalar field as defined in
+ *          the Aztec Protocol Specs.
+ */
+export type GrumpkinScalar = Fq;
+export const GrumpkinScalar = Fq;

package/src/{fields → curves/grumpkin}/point.ts

@@ -1,10 +1,10 @@
-import { toBigIntBE } from '../bigint-buffer/index.js';
-import { poseidon2Hash } from '../crypto/poseidon/index.js';
-import { randomBoolean } from '../crypto/random/index.js';
-import { hexSchemaFor } from '../schemas/utils.js';
-import { BufferReader, FieldReader, serializeToBuffer } from '../serialize/index.js';
-import { bufferToHex, hexToBuffer } from '../string/index.js';
-import { Fr } from './fields.js';
+import { toBigIntBE } from '../../bigint-buffer/index.js';
+import { poseidon2Hash } from '../../crypto/poseidon/index.js';
+import { randomBoolean } from '../../crypto/random/index.js';
+import { hexSchemaFor } from '../../schemas/utils.js';
+import { BufferReader, FieldReader, serializeToBuffer } from '../../serialize/index.js';
+import { bufferToHex, hexToBuffer } from '../../string/index.js';
+import { Fr } from '../bn254/field.js';
 
 /**
  * Represents a Point on an elliptic curve with x and y coordinates.

package/src/eth-address/index.ts

@@ -2,7 +2,7 @@ import { inspect } from 'util';
 
 import { keccak256String } from '../crypto/keccak/index.js';
 import { randomBytes } from '../crypto/random/index.js';
-import { Fr } from '../fields/index.js';
+import { Fr } from '../curves/bn254/index.js';
 import { hexSchemaFor } from '../schemas/utils.js';
 import { BufferReader, FieldReader } from '../serialize/index.js';
 import { TypeRegistry } from '../serialize/type_registry.js';
@@ -249,7 +249,7 @@ export class EthAddress {
   /** Converts a number into an address. Useful for testing. */
   static fromNumber(num: bigint | number): EthAddress {
     const buffer = Buffer.alloc(EthAddress.SIZE_IN_BYTES);
-    buffer.writeBigUInt64BE(BigInt(num), 0);
+    buffer.writeBigUInt64BE(BigInt(num), EthAddress.SIZE_IN_BYTES - 8);
     return new EthAddress(buffer);
   }
 
@@ -261,6 +261,12 @@ export class EthAddress {
     // Serialization from hex string.
     return hexSchemaFor(EthAddress, EthAddress.isAddress);
   }
+
+  static areEqual(a: EthAddress | string, b: EthAddress | string) {
+    const addrA = typeof a === 'string' ? EthAddress.fromString(a) : a;
+    const addrB = typeof b === 'string' ? EthAddress.fromString(b) : b;
+    return addrA.equals(addrB);
+  }
 }
 
 // For deserializing JSON.

package/src/iterator/filter.ts

@@ -0,0 +1,11 @@
+/** Wraps an async iterable iterator such that it filters values based on a predicate. */
+export async function* filter<T>(
+  iterator: AsyncIterableIterator<T>,
+  predicate: (item: T) => boolean | Promise<boolean>,
+): AsyncIterableIterator<T> {
+  for await (const item of iterator) {
+    if (await predicate(item)) {
+      yield item;
+    }
+  }
+}

package/src/iterator/index.ts

@@ -0,0 +1 @@
+export { filter } from './filter.js';

package/src/jest/setup.mjs

@@ -1,3 +1,4 @@
+import { parseBooleanEnv } from '@aztec/foundation/config';
 import { overwriteLoggingStream, pinoPrettyOpts } from '@aztec/foundation/log';
 
 import pretty from 'pino-pretty';
@@ -6,4 +7,6 @@ import pretty from 'pino-pretty';
 // file so we don't mess up with dependencies in non-testing environments,
 // since pino-pretty messes up with browser bundles.
 // See also https://www.npmjs.com/package/pino-pretty?activeTab=readme#user-content-usage-with-jest
-overwriteLoggingStream(pretty(pinoPrettyOpts));
+if (!parseBooleanEnv(process.env.LOG_JSON)) {
+  overwriteLoggingStream(pretty(pinoPrettyOpts));
+}

package/src/json-rpc/client/undici.ts

@@ -1,3 +1,5 @@
+import { promisify } from 'node:util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'node:zlib';
 import { Agent, type Dispatcher } from 'undici';
 
 import { createLogger } from '../../log/pino-logger.js';
@@ -5,8 +7,14 @@ import { NoRetryError } from '../../retry/index.js';
 import { jsonStringify } from '../convert.js';
 import type { JsonRpcFetch } from './fetch.js';
 
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
 const log = createLogger('json-rpc:json_rpc_client:undici');
 
+/** Minimum request size in bytes to trigger compression. */
+const COMPRESSION_THRESHOLD = 1024;
+
 export { Agent };
 
 export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
@@ -14,14 +22,18 @@ export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
     log.trace(`JsonRpcClient.fetch: ${host}`, { host, body });
     let resp: Dispatcher.ResponseData;
     try {
+      const jsonBody = Buffer.from(jsonStringify(body));
+      const shouldCompress = jsonBody.length >= COMPRESSION_THRESHOLD;
       resp = await client.request({
         method: 'POST',
         origin: new URL(host),
         path: '/',
-        body: jsonStringify(body),
+        body: shouldCompress ? await gzip(jsonBody) : jsonBody,
         headers: {
           ...extraHeaders,
           'content-type': 'application/json',
+          ...(shouldCompress && { 'content-encoding': 'gzip' }),
+          'accept-encoding': 'gzip',
         },
       });
     } catch (err) {
@@ -31,13 +43,19 @@ export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
 
     let responseJson: any;
     const responseOk = resp.statusCode >= 200 && resp.statusCode <= 299;
+    const contentEncoding = resp.headers['content-encoding'];
     try {
-      responseJson = await resp.body.json();
+      if (contentEncoding === 'gzip') {
+        const jsonBuffer = await gunzip(await resp.body.arrayBuffer());
+        responseJson = JSON.parse(jsonBuffer.toString('utf-8'));
+      } else {
+        responseJson = await resp.body.json();
+      }
     } catch {
       if (!responseOk) {
         throw new Error('HTTP ' + resp.statusCode);
       }
-      throw new Error(`Failed to parse body as JSON: ${await resp.body.text()}`);
+      throw new Error(`Failed to parse body as JSON. encoding: ${contentEncoding}, body: ${await resp.body.text()}`);
     }
 
     if (!responseOk) {

package/src/json-rpc/server/safe_json_rpc_server.ts

@@ -35,7 +35,7 @@ export type SafeJsonRpcServerConfig = {
 const defaultServerConfig: SafeJsonRpcServerConfig = {
   http200OnError: false,
   maxBatchSize: 100,
-  maxBodySizeBytes: '50mb',
+  maxBodySizeBytes: '1mb',
 };
 
 export class SafeJsonRpcServer {

package/src/log/libp2p_logger.ts

@@ -2,15 +2,17 @@ import type { ComponentLogger, Logger } from '@libp2p/interface';
 
 import { getLogLevelFromFilters } from './log-filters.js';
 import type { LogLevel } from './log-levels.js';
-import { logFilters, logger } from './pino-logger.js';
+import { type LoggerBindings, logFilters, logger } from './pino-logger.js';
 
 /**
  * Creates a libp2p compatible logger that wraps our pino logger.
  * This adapter implements the ComponentLogger interface required by libp2p.
+ * @param namespace - Base namespace for the logger
+ * @param bindings - Optional bindings to pass to the logger (actor, instanceId)
  */
-export function createLibp2pComponentLogger(namespace: string): ComponentLogger {
+export function createLibp2pComponentLogger(namespace: string, bindings?: LoggerBindings): ComponentLogger {
   return {
-    forComponent: (component: string) => createLibp2pLogger(`${namespace}:${component}`),
+    forComponent: (component: string) => createLibp2pLogger(`${namespace}:${component}`, bindings),
   };
 }
 
@@ -24,9 +26,14 @@ function replaceFormatting(message: string) {
   return message.replace(/(%p|%a)/g, '%s');
 }
 
-function createLibp2pLogger(component: string): Logger {
+function createLibp2pLogger(component: string, bindings?: LoggerBindings): Logger {
   // Create a direct pino logger instance for libp2p that supports string interpolation
-  const log = logger.child({ module: component }, { level: getLogLevelFromFilters(logFilters, component) });
+  const actor = bindings?.actor;
+  const instanceId = bindings?.instanceId;
+  const log = logger.child(
+    { module: component, ...(actor && { actor }), ...(instanceId && { instanceId }) },
+    { level: getLogLevelFromFilters(logFilters, component) },
+  );
 
   const logIfEnabled = (level: LogLevel, message: string, ...args: unknown[]) => {
     if (!log.isLevelEnabled(level)) {

package/src/log/pino-logger-server.ts

@@ -0,0 +1,25 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import { type LoggerBindings, addLogBindingsHandler, removeLogBindingsHandler } from './pino-logger.js';
+
+/** AsyncLocalStorage for logger bindings context propagation (Node.js only). */
+const bindingsStorage = new AsyncLocalStorage<LoggerBindings>();
+
+/** Returns the current bindings from AsyncLocalStorage, if any. */
+export function getBindings(): LoggerBindings | undefined {
+  return bindingsStorage.getStore();
+}
+
+/**
+ * Runs a callback within a bindings context. All loggers created within the callback
+ * will automatically inherit the bindings (actor, instanceId) via the log bindings handler.
+ */
+export async function withLoggerBindings<T>(bindings: LoggerBindings, callback: () => Promise<T>): Promise<T> {
+  const handler = () => bindingsStorage.getStore();
+  addLogBindingsHandler(handler);
+  try {
+    return await bindingsStorage.run(bindings, callback);
+  } finally {
+    removeLogBindingsHandler(handler);
+  }
+}

package/src/log/pino-logger.ts

@@ -1,19 +1,62 @@
-import { createColors, isColorSupported } from 'colorette';
+import { type Color, createColors, isColorSupported } from 'colorette';
 import isNode from 'detect-node';
 import { pino, symbols } from 'pino';
 import type { Writable } from 'stream';
 import { inspect } from 'util';
 
 import { compactArray } from '../collection/array.js';
-import { type EnvVar, parseBooleanEnv } from '../config/index.js';
+import type { EnvVar } from '../config/index.js';
+import { parseBooleanEnv } from '../config/parse-env.js';
 import { GoogleCloudLoggerConfig } from './gcloud-logger-config.js';
 import { getLogLevelFromFilters, parseEnv } from './log-filters.js';
 import type { LogLevel } from './log-levels.js';
 import type { LogData, LogFn } from './log_fn.js';
 
-export function createLogger(module: string): Logger {
-  module = logNameHandlers.reduce((moduleName, handler) => handler(moduleName), module.replace(/^aztec:/, ''));
-  const pinoLogger = logger.child({ module }, { level: getLogLevelFromFilters(logFilters, module) });
+/** Optional bindings to pass to createLogger for additional context. */
+export type LoggerBindings = {
+  /** Actor label shown in logs (e.g., 'MAIN', 'prover-node'). */
+  actor?: string;
+  /** Instance identifier for distinguishing multiple instances of the same component. */
+  instanceId?: string;
+};
+
+// Allow global hooks for providing default bindings.
+// Used by withLoggerBindings in pino-logger-server to propagate bindings via AsyncLocalStorage.
+type LogBindingsHandler = () => LoggerBindings | undefined;
+const logBindingsHandlers: LogBindingsHandler[] = [];
+
+export function addLogBindingsHandler(handler: LogBindingsHandler): void {
+  logBindingsHandlers.push(handler);
+}
+
+export function removeLogBindingsHandler(handler: LogBindingsHandler) {
+  const index = logBindingsHandlers.indexOf(handler);
+  if (index !== -1) {
+    logBindingsHandlers.splice(index, 1);
+  }
+}
+
+function getBindingsFromHandlers(): LoggerBindings | undefined {
+  for (const handler of logBindingsHandlers) {
+    const bindings = handler();
+    if (bindings) {
+      return bindings;
+    }
+  }
+  return undefined;
+}
+
+export function createLogger(module: string, bindings?: LoggerBindings): Logger {
+  module = module.replace(/^aztec:/, '');
+
+  const resolvedBindings = { ...getBindingsFromHandlers(), ...bindings };
+  const actor = resolvedBindings?.actor;
+  const instanceId = resolvedBindings?.instanceId;
+
+  const pinoLogger = logger.child(
+    { module, ...(actor && { actor }), ...(instanceId && { instanceId }) },
+    { level: getLogLevelFromFilters(logFilters, module) },
+  );
 
   // We check manually for isLevelEnabled to avoid calling processLogData unnecessarily.
   // Note that isLevelEnabled is missing from the browser version of pino.
@@ -43,11 +86,24 @@ export function createLogger(module: string): Logger {
     isLevelEnabled: (level: LogLevel) => isLevelEnabled(pinoLogger, level),
     /** Module name for the logger. */
     module,
-    /** Creates another logger by extending this logger module name. */
-    createChild: (childModule: string) => createLogger(`${module}:${childModule}`),
+    /** Creates another logger by extending this logger module name and preserving bindings. */
+    createChild: (childModule: string) => createLogger(`${module}:${childModule}`, { actor, instanceId }),
+    /** Returns the bindings (actor, instanceId) for this logger. */
+    getBindings: () => ({ actor, instanceId }),
   };
 }
 
+/**
+ * Returns a logger for the given module. If loggerOrBindings is already a Logger, returns it directly.
+ * Otherwise, creates a new logger with the given module name and bindings.
+ */
+export function resolveLogger(module: string, loggerOrBindings?: Logger | LoggerBindings): Logger {
+  if (loggerOrBindings && 'info' in loggerOrBindings) {
+    return loggerOrBindings as Logger;
+  }
+  return createLogger(module, loggerOrBindings);
+}
+
 // Allow global hooks for processing log data.
 // Used for injecting OTEL trace_id in telemetry client.
 type LogDataHandler = (data: LogData) => LogData;
@@ -61,31 +117,6 @@ function processLogData(data: LogData): LogData {
   return logDataHandlers.reduce((accum, handler) => handler(accum), data);
 }
 
-// Allow global hooks for tweaking module names.
-// Used in tests to add a uid to modules, so we can differentiate multiple nodes in the same process.
-type LogNameHandler = (module: string) => string;
-const logNameHandlers: LogNameHandler[] = [];
-
-export function addLogNameHandler(handler: LogNameHandler): void {
-  logNameHandlers.push(handler);
-}
-
-export function removeLogNameHandler(handler: LogNameHandler) {
-  const index = logNameHandlers.indexOf(handler);
-  if (index !== -1) {
-    logNameHandlers.splice(index, 1);
-  }
-}
-
-/** Creates all loggers within the given callback with the suffix appended to the module name. */
-export async function withLogNameSuffix<T>(suffix: string, callback: () => Promise<T>): Promise<T> {
-  const logNameHandler = (module: string) => `${module}:${suffix}`;
-  addLogNameHandler(logNameHandler);
-  const result = await callback();
-  removeLogNameHandler(logNameHandler);
-  return result;
-}
-
 // Patch isLevelEnabled missing from pino/browser.
 function isLevelEnabled(logger: pino.Logger<'verbose', boolean>, level: LogLevel): boolean {
   return typeof logger.isLevelEnabled === 'function'
@@ -145,22 +176,90 @@ export const levels = {
 // Transport options for pretty logging to stderr via pino-pretty.
 const colorEnv = process.env['FORCE_COLOR' satisfies EnvVar];
 const useColor = colorEnv === undefined ? isColorSupported : parseBooleanEnv(colorEnv);
-const { bold, reset } = createColors({ useColor });
-export const pinoPrettyOpts = {
+const { bold, reset, cyan, magenta, yellow, blue, green, magentaBright, yellowBright, blueBright, greenBright } =
+  createColors({ useColor });
+
+// Per-actor coloring: each unique actor gets a different color for easier visual distinction.
+// Disabled when LOG_NO_COLOR_PER_ACTOR is set to a truthy value.
+const useColorPerActor = useColor && !parseBooleanEnv(process.env['LOG_NO_COLOR_PER_ACTOR' satisfies EnvVar]);
+const actorColors: Color[] = [yellow, magenta, blue, green, magentaBright, yellowBright, blueBright, greenBright];
+const actorColorMap = new Map<string, Color>();
+let nextColorIndex = 0;
+
+/** Returns the color function assigned to a given actor, assigning a new one if needed. */
+export function getActorColor(actor: string): Color {
+  let color = actorColorMap.get(actor);
+  if (!color) {
+    color = actorColors[nextColorIndex % actorColors.length];
+    actorColorMap.set(actor, color);
+    nextColorIndex++;
+  }
+  return color;
+}
+
+/** Resets the actor-to-color mapping. Useful for testing. */
+export function resetActorColors(): void {
+  actorColorMap.clear();
+  nextColorIndex = 0;
+}
+
+// String template for messageFormat (used in worker threads and when per-actor coloring is disabled).
+const messageFormatString = `${bold('{module}')}{if actor} ${cyan('{actor}')}{end}{if instanceId} ${reset(cyan('{instanceId}'))}{end} ${reset('{msg}')}`;
+
+// Function for messageFormat when per-actor coloring is enabled (can only be used in-process, not worker threads).
+type LogObject = { actor?: string; module?: string; instanceId?: string; msg?: string };
+
+/** Formats a log message with per-actor coloring. Actor, module, and instanceId share the same color. */
+export function formatLogMessage(log: LogObject, messageKey: string): string {
+  const actor = log.actor;
+  const module = log.module ?? '';
+  const instanceId = log.instanceId;
+  const msg = log[messageKey as keyof LogObject] ?? '';
+
+  // Use actor color for actor, module, and instanceId when actor is present
+  const color = actor ? getActorColor(actor) : cyan;
+
+  let result = bold(color(module));
+  if (actor) {
+    result += ' ' + color(actor);
+  }
+  if (instanceId) {
+    result += ' ' + reset(color(instanceId));
+  }
+  result += ' ' + reset(String(msg));
+  return result;
+}
+
+// Base options for pino-pretty (shared between transport and direct use).
+const pinoPrettyBaseOpts = {
   destination: 2,
   sync: true,
   colorize: useColor,
-  ignore: 'module,pid,hostname,trace_id,span_id,trace_flags,severity',
-  messageFormat: `${bold('{module}')} ${reset('{msg}')}`,
+  ignore: 'module,actor,instanceId,pid,hostname,trace_id,span_id,trace_flags,severity',
   customLevels: 'fatal:60,error:50,warn:40,info:30,verbose:25,debug:20,trace:10',
   customColors: 'fatal:bgRed,error:red,warn:yellow,info:green,verbose:magenta,debug:blue,trace:gray',
   minimumLevel: 'trace' as const,
   singleLine: !parseBooleanEnv(process.env['LOG_MULTILINE' satisfies EnvVar]),
 };
 
+/**
+ * Pino-pretty options for direct use (e.g., jest/setup.mjs).
+ * Includes function-based messageFormat for per-actor coloring when enabled.
+ */
+export const pinoPrettyOpts = {
+  ...pinoPrettyBaseOpts,
+  messageFormat: useColorPerActor ? formatLogMessage : messageFormatString,
+};
+
+// Transport options use string template only (functions can't be serialized to worker threads).
+const prettyTransportOpts = {
+  ...pinoPrettyBaseOpts,
+  messageFormat: messageFormatString,
+};
+
 const prettyTransport: pino.TransportTargetOptions = {
   target: 'pino-pretty',
-  options: pinoPrettyOpts,
+  options: prettyTransportOpts,
   level: 'trace',
 };
 
@@ -261,6 +360,8 @@ export type Logger = { [K in LogLevel]: LogFn } & { /** Error log function */ er
   isLevelEnabled: (level: LogLevel) => boolean;
   module: string;
   createChild: (childModule: string) => Logger;
+  /** Returns the bindings (actor, instanceId) for this logger. */
+  getBindings: () => LoggerBindings;
 };
 
 /**

package/src/queue/semaphore.ts

@@ -1,5 +1,10 @@
 import { FifoMemoryQueue } from './fifo_memory_queue.js';
 
+export interface ISemaphore {
+  acquire(): Promise<void>;
+  release(): void;
+}
+
 /**
  * Allows the acquiring of up to `size` tokens before calls to acquire block, waiting for a call to release().
  */

package/src/retry/index.ts

@@ -103,3 +103,21 @@ export async function retryUntil<T>(
     }
   }
 }
+
+/**
+ * Convenience wrapper around retryUntil with fast polling for tests.
+ * Uses 10s timeout and 100ms polling interval by default.
+ *
+ * @param fn - The function to retry until it returns a truthy value.
+ * @param name - Description of what we're waiting for (for error messages).
+ * @param timeout - Optional timeout in seconds. Defaults to 10s.
+ * @param interval - Optional interval in seconds. Defaults to 0.1s (100ms).
+ */
+export function retryFastUntil<T>(
+  fn: () => (T | undefined) | Promise<T | undefined>,
+  name = '',
+  timeout = 10,
+  interval = 0.1,
+) {
+  return retryUntil(fn, name, timeout, interval);
+}