@aztec/simulator 5.0.0-nightly.20260616 → 5.0.0-nightly.20260618

package/dest/client.d.ts

@@ -1,7 +1,5 @@
 export * from './private/acvm/index.js';
 export { WASMSimulator } from './private/acvm_wasm.js';
-export { SimulatorRecorderWrapper } from './private/circuit_recording/simulator_recorder_wrapper.js';
-export { MemoryCircuitRecorder } from './private/circuit_recording/memory_circuit_recorder.js';
 export { type CircuitSimulator, type DecodedError } from './private/circuit_simulator.js';
 export * from './common/index.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpZW50LmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY2xpZW50LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsT0FBTyxFQUFFLGFBQWEsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBQ3ZELE9BQU8sRUFBRSx3QkFBd0IsRUFBRSxNQUFNLDJEQUEyRCxDQUFDO0FBQ3JHLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxNQUFNLHdEQUF3RCxDQUFDO0FBQy9GLE9BQU8sRUFBRSxLQUFLLGdCQUFnQixFQUFFLEtBQUssWUFBWSxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDMUYsY0FBYyxtQkFBbUIsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpZW50LmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY2xpZW50LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsT0FBTyxFQUFFLGFBQWEsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBQ3ZELE9BQU8sRUFBRSxLQUFLLGdCQUFnQixFQUFFLEtBQUssWUFBWSxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDMUYsY0FBYyxtQkFBbUIsQ0FBQyJ9

package/dest/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2DAA2D,CAAC;AACrG,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAC/F,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC1F,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC1F,cAAc,mBAAmB,CAAC"}

package/dest/client.js

@@ -1,5 +1,3 @@
 export * from './private/acvm/index.js';
 export { WASMSimulator } from './private/acvm_wasm.js';
-export { SimulatorRecorderWrapper } from './private/circuit_recording/simulator_recorder_wrapper.js';
-export { MemoryCircuitRecorder } from './private/circuit_recording/memory_circuit_recorder.js';
 export * from './common/index.js';

package/dest/private/circuit_recording/circuit_recorder.d.ts

@@ -21,10 +21,22 @@ export declare class CircuitRecording {
     constructor(circuitName: string, functionName: string, bytecodeSHA512Hash: string, inputs: Record<string, string>);
     setParent(recording?: CircuitRecording): void;
 }
+/** Inputs needed to open a recording for a single circuit execution. */
+export type RecordingMetadata = {
+    input: ACVMWitness;
+    bytecode: Buffer;
+    circuitName: string;
+    functionName: string;
+};
 /**
  * Class responsible for recording circuit inputs necessary to replay the circuit. These inputs are the initial witness
  * map and the oracle calls made during the circuit execution/witness generation.
  *
+ * The active recording for an execution lives in `AsyncLocalStorage`, so each (possibly nested) circuit execution owns
+ * its own recording and concurrent or re-entrant executions cannot corrupt one another's state. Nested executions
+ * (`aztec_prv_callPrivateFunction`, utility calls) re-enter {@link record}, which links the child to the recording
+ * active in the enclosing async context and lets ALS restore the parent automatically when the child completes.
+ *
  * Example recording object:
  * ```json
  * {
@@ -69,20 +81,21 @@ export declare class CircuitRecording {
 export declare class CircuitRecorder {
     #private;
     protected readonly logger: Logger;
-    protected recording?: CircuitRecording;
-    private stackDepth;
-    private newCircuit;
     protected constructor(loggerOrBindings?: Logger | LoggerBindings);
     /**
-     * Initializes a new circuit recording session.
-     * @param recordDir - Directory to store the recording
-     * @param input - Circuit input witness
-     * @param circuitBytecode - Compiled circuit bytecode
-     * @param circuitName - Name of the circuit
-     * @param functionName - Name of the circuit function (defaults to 'main'). This is meaningful only for
-     * contracts as protocol circuits artifacts always contain a single entrypoint function called 'main'.
+     * Records a single circuit execution. Opens a recording for the circuit (linked as a child of the recording active
+     * in the current async context, if any), runs `fn` within that recording's context, and finalizes it. The recording
+     * is returned alongside the result so callers can derive per-circuit stats (e.g. oracle timings).
+     *
+     * Recorder bookkeeping never alters execution: if `fn` throws, the error is attached to the recording and re-thrown
+     * unchanged.
+     * @param metadata - Identifies the circuit and its initial witness.
+     * @param fn - Runs the circuit execution; its oracle calls are recorded into this recording.
      */
-    start(input: ACVMWitness, circuitBytecode: Buffer, circuitName: string, functionName: string): Promise<void>;
+    record<T>(metadata: RecordingMetadata, fn: () => Promise<T>): Promise<{
+        result: T;
+        recording: CircuitRecording;
+    }>;
     /**
      * Wraps a callback to record all oracle/foreign calls.
      * @param callback - The original callback to wrap, either a user circuit callback or protocol circuit callback.
@@ -90,20 +103,20 @@ export declare class CircuitRecorder {
      */
     wrapCallback(callback: ACIRCallback | ForeignCallHandler | undefined): ACIRCallback | ForeignCallHandler | undefined;
     /**
-     * Records a single oracle/foreign call with its inputs and outputs.
+     * Records a single oracle/foreign call with its inputs and outputs against the recording active in the current
+     * async context.
      * @param name - Name of the call
      * @param inputs - Input arguments
      * @param outputs - Output results
      */
-    recordCall(name: string, inputs: unknown[], outputs: unknown, time: number, stackDepth: number): Promise<OracleCall>;
-    /**
-     * Finalizes the recording by resetting the state and returning the recording object.
-     */
-    finish(): Promise<CircuitRecording>;
-    /**
-     * Finalizes the recording by resetting the state and returning the recording object with an attached error.
-     * @param error - The error that occurred during circuit execution
-     */
-    finishWithError(error: unknown): Promise<CircuitRecording>;
+    recordCall(name: string, inputs: unknown[], outputs: unknown, time: number): Promise<OracleCall>;
+    /** The recording active in the current async context, if any. */
+    protected currentRecording(): CircuitRecording | undefined;
+    /** Hook invoked when a recording opens, within the recording's context. Overridden to persist recordings. */
+    protected onStart(_recording: CircuitRecording): Promise<void>;
+    /** Hook invoked when a recording completes successfully, within the recording's context. */
+    protected onFinish(_recording: CircuitRecording): Promise<void>;
+    /** Hook invoked when a recording's execution throws, within the recording's context. */
+    protected onError(_recording: CircuitRecording, _error: unknown): Promise<void>;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2lyY3VpdF9yZWNvcmRlci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3ByaXZhdGUvY2lyY3VpdF9yZWNvcmRpbmcvY2lyY3VpdF9yZWNvcmRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQUUsS0FBSyxNQUFNLEVBQUUsS0FBSyxjQUFjLEVBQWlCLE1BQU0sdUJBQXVCLENBQUM7QUFFeEYsT0FBTyxLQUFLLEVBQUUsa0JBQWtCLEVBQXVDLE1BQU0scUJBQXFCLENBQUM7QUFFbkcsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFDcEQsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFFekQsTUFBTSxNQUFNLFVBQVUsR0FBRztJQUN2QixJQUFJLEVBQUUsTUFBTSxDQUFDO0lBQ2IsTUFBTSxFQUFFLE9BQU8sRUFBRSxDQUFDO0lBQ2xCLE9BQU8sRUFBRSxPQUFPLENBQUM7SUFDakIsSUFBSSxFQUFFLE1BQU0sQ0FBQztJQU1iLFVBQVUsRUFBRSxNQUFNLENBQUM7Q0FDcEIsQ0FBQztBQUVGLHFCQUFhLGdCQUFnQjtJQUMzQixXQUFXLEVBQUUsTUFBTSxDQUFDO0lBQ3BCLFlBQVksRUFBRSxNQUFNLENBQUM7SUFDckIsa0JBQWtCLEVBQUUsTUFBTSxDQUFDO0lBQzNCLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsTUFBTSxFQUFFLE1BQU0sQ0FBQyxNQUFNLEVBQUUsTUFBTSxDQUFDLENBQUM7SUFDL0IsV0FBVyxFQUFFLFVBQVUsRUFBRSxDQUFDO0lBQzFCLEtBQUssQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNmLE1BQU0sQ0FBQyxFQUFFLGdCQUFnQixDQUFDO0lBRTFCLFlBQVksV0FBVyxFQUFFLE1BQU0sRUFBRSxZQUFZLEVBQUUsTUFBTSxFQUFFLGtCQUFrQixFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsTUFBTSxDQUFDLE1BQU0sRUFBRSxNQUFNLENBQUMsRUFPaEg7SUFFRCxTQUFTLENBQUMsU0FBUyxDQUFDLEVBQUUsZ0JBQWdCLEdBQUcsSUFBSSxDQUU1QztDQUNGO0FBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBNENHO0FBQ0gscUJBQWEsZUFBZTs7SUFDMUIsU0FBUyxDQUFDLFFBQVEsQ0FBQyxNQUFNLEVBQUUsTUFBTSxDQUFDO0lBRWxDLFNBQVMsQ0FBQyxTQUFTLENBQUMsRUFBRSxnQkFBZ0IsQ0FBQztJQUV2QyxPQUFPLENBQUMsVUFBVSxDQUFhO0lBQy9CLE9BQU8sQ0FBQyxVQUFVLENBQWlCO0lBRW5DLFNBQVMsYUFBYSxnQkFBZ0IsQ0FBQyxFQUFFLE1BQU0sR0FBRyxjQUFjLEVBRS9EO0lBRUQ7Ozs7Ozs7O09BUUc7SUFDSCxLQUFLLENBQUMsS0FBSyxFQUFFLFdBQVcsRUFBRSxlQUFlLEVBQUUsTUFBTSxFQUFFLFdBQVcsRUFBRSxNQUFNLEVBQUUsWUFBWSxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBYTNHO0lBRUQ7Ozs7T0FJRztJQUNILFlBQVksQ0FBQyxRQUFRLEVBQUUsWUFBWSxHQUFHLGtCQUFrQixHQUFHLFNBQVMsR0FBRyxZQUFZLEdBQUcsa0JBQWtCLEdBQUcsU0FBUyxDQVFuSDtJQTZFRDs7Ozs7T0FLRztJQUNILFVBQVUsQ0FBQyxJQUFJLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRSxPQUFPLEVBQUUsRUFBRSxPQUFPLEVBQUUsT0FBTyxFQUFFLElBQUksRUFBRSxNQUFNLEVBQUUsVUFBVSxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsVUFBVSxDQUFDLENBVW5IO0lBRUQ7O09BRUc7SUFDSCxNQUFNLElBQUksT0FBTyxDQUFDLGdCQUFnQixDQUFDLENBY2xDO0lBRUQ7OztPQUdHO0lBQ0csZUFBZSxDQUFDLEtBQUssRUFBRSxPQUFPLEdBQUcsT0FBTyxDQUFDLGdCQUFnQixDQUFDLENBSS9EO0NBQ0YifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2lyY3VpdF9yZWNvcmRlci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3ByaXZhdGUvY2lyY3VpdF9yZWNvcmRpbmcvY2lyY3VpdF9yZWNvcmRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQUUsS0FBSyxNQUFNLEVBQUUsS0FBSyxjQUFjLEVBQWlCLE1BQU0sdUJBQXVCLENBQUM7QUFFeEYsT0FBTyxLQUFLLEVBQUUsa0JBQWtCLEVBQXVDLE1BQU0scUJBQXFCLENBQUM7QUFJbkcsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFDcEQsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFFekQsTUFBTSxNQUFNLFVBQVUsR0FBRztJQUN2QixJQUFJLEVBQUUsTUFBTSxDQUFDO0lBQ2IsTUFBTSxFQUFFLE9BQU8sRUFBRSxDQUFDO0lBQ2xCLE9BQU8sRUFBRSxPQUFPLENBQUM7SUFDakIsSUFBSSxFQUFFLE1BQU0sQ0FBQztJQU1iLFVBQVUsRUFBRSxNQUFNLENBQUM7Q0FDcEIsQ0FBQztBQUVGLHFCQUFhLGdCQUFnQjtJQUMzQixXQUFXLEVBQUUsTUFBTSxDQUFDO0lBQ3BCLFlBQVksRUFBRSxNQUFNLENBQUM7SUFDckIsa0JBQWtCLEVBQUUsTUFBTSxDQUFDO0lBQzNCLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsTUFBTSxFQUFFLE1BQU0sQ0FBQyxNQUFNLEVBQUUsTUFBTSxDQUFDLENBQUM7SUFDL0IsV0FBVyxFQUFFLFVBQVUsRUFBRSxDQUFDO0lBQzFCLEtBQUssQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNmLE1BQU0sQ0FBQyxFQUFFLGdCQUFnQixDQUFDO0lBRTFCLFlBQVksV0FBVyxFQUFFLE1BQU0sRUFBRSxZQUFZLEVBQUUsTUFBTSxFQUFFLGtCQUFrQixFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsTUFBTSxDQUFDLE1BQU0sRUFBRSxNQUFNLENBQUMsRUFPaEg7SUFFRCxTQUFTLENBQUMsU0FBUyxDQUFDLEVBQUUsZ0JBQWdCLEdBQUcsSUFBSSxDQUU1QztDQUNGO0FBRUQsd0VBQXdFO0FBQ3hFLE1BQU0sTUFBTSxpQkFBaUIsR0FBRztJQUM5QixLQUFLLEVBQUUsV0FBVyxDQUFDO0lBQ25CLFFBQVEsRUFBRSxNQUFNLENBQUM7SUFDakIsV0FBVyxFQUFFLE1BQU0sQ0FBQztJQUNwQixZQUFZLEVBQUUsTUFBTSxDQUFDO0NBQ3RCLENBQUM7QUFFRjs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQWlERztBQUNILHFCQUFhLGVBQWU7O0lBQzFCLFNBQVMsQ0FBQyxRQUFRLENBQUMsTUFBTSxFQUFFLE1BQU0sQ0FBQztJQUlsQyxTQUFTLGFBQWEsZ0JBQWdCLENBQUMsRUFBRSxNQUFNLEdBQUcsY0FBYyxFQUUvRDtJQUVEOzs7Ozs7Ozs7T0FTRztJQUNILE1BQU0sQ0FBQyxDQUFDLEVBQUUsUUFBUSxFQUFFLGlCQUFpQixFQUFFLEVBQUUsRUFBRSxNQUFNLE9BQU8sQ0FBQyxDQUFDLENBQUMsR0FBRyxPQUFPLENBQUM7UUFBRSxNQUFNLEVBQUUsQ0FBQyxDQUFDO1FBQUMsU0FBUyxFQUFFLGdCQUFnQixDQUFBO0tBQUUsQ0FBQyxDQXNCaEg7SUFFRDs7OztPQUlHO0lBQ0gsWUFBWSxDQUFDLFFBQVEsRUFBRSxZQUFZLEdBQUcsa0JBQWtCLEdBQUcsU0FBUyxHQUFHLFlBQVksR0FBRyxrQkFBa0IsR0FBRyxTQUFTLENBUW5IO0lBeUREOzs7Ozs7T0FNRztJQUNILFVBQVUsQ0FBQyxJQUFJLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRSxPQUFPLEVBQUUsRUFBRSxPQUFPLEVBQUUsT0FBTyxFQUFFLElBQUksRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLFVBQVUsQ0FBQyxDQWEvRjtJQUVELGlFQUFpRTtJQUNqRSxTQUFTLENBQUMsZ0JBQWdCLElBQUksZ0JBQWdCLEdBQUcsU0FBUyxDQUV6RDtJQUVELDZHQUE2RztJQUM3RyxTQUFTLENBQUMsT0FBTyxDQUFDLFVBQVUsRUFBRSxnQkFBZ0IsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBRTdEO0lBRUQsNEZBQTRGO0lBQzVGLFNBQVMsQ0FBQyxRQUFRLENBQUMsVUFBVSxFQUFFLGdCQUFnQixHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFOUQ7SUFFRCx3RkFBd0Y7SUFDeEYsU0FBUyxDQUFDLE9BQU8sQ0FBQyxVQUFVLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxFQUFFLE9BQU8sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBRTlFO0NBQ0YifQ==

package/dest/private/circuit_recording/circuit_recorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"circuit_recorder.d.ts","sourceRoot":"","sources":["../../../src/private/circuit_recording/circuit_recorder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAiB,MAAM,uBAAuB,CAAC;AAExF,OAAO,KAAK,EAAE,kBAAkB,EAAuC,MAAM,qBAAqB,CAAC;AAEnG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IAMb,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,gBAAgB;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAE1B,YAAY,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAOhH;IAED,SAAS,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAE5C;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,eAAe;;IAC1B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAElC,SAAS,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAEvC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAiB;IAEnC,SAAS,aAAa,gBAAgB,CAAC,EAAE,MAAM,GAAG,cAAc,EAE/D;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAa3G;IAED;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,kBAAkB,GAAG,SAAS,GAAG,YAAY,GAAG,kBAAkB,GAAG,SAAS,CAQnH;IA6ED;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAUnH;IAED;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAclC;IAED;;;OAGG;IACG,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAI/D;CACF"}
+{"version":3,"file":"circuit_recorder.d.ts","sourceRoot":"","sources":["../../../src/private/circuit_recording/circuit_recorder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAiB,MAAM,uBAAuB,CAAC;AAExF,OAAO,KAAK,EAAE,kBAAkB,EAAuC,MAAM,qBAAqB,CAAC;AAInG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IAMb,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,gBAAgB;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAE1B,YAAY,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAOhH;IAED,SAAS,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAE5C;CACF;AAED,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,eAAe;;IAC1B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlC,SAAS,aAAa,gBAAgB,CAAC,EAAE,MAAM,GAAG,cAAc,EAE/D;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,CAAC,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAsBhH;IAED;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,kBAAkB,GAAG,SAAS,GAAG,YAAY,GAAG,kBAAkB,GAAG,SAAS,CAQnH;IAyDD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAa/F;IAED,iEAAiE;IACjE,SAAS,CAAC,gBAAgB,IAAI,gBAAgB,GAAG,SAAS,CAEzD;IAED,6GAA6G;IAC7G,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7D;IAED,4FAA4F;IAC5F,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;IAED,wFAAwF;IACxF,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9E;CACF"}

package/dest/private/circuit_recording/circuit_recorder.js

@@ -1,6 +1,7 @@
 import { sha512 } from '@aztec/foundation/crypto/sha512';
 import { resolveLogger } from '@aztec/foundation/log';
 import { Timer } from '@aztec/foundation/timer';
+import { AsyncLocalStorage } from 'node:async_hooks';
 export class CircuitRecording {
     circuitName;
     functionName;
@@ -26,6 +27,11 @@ export class CircuitRecording {
  * Class responsible for recording circuit inputs necessary to replay the circuit. These inputs are the initial witness
  * map and the oracle calls made during the circuit execution/witness generation.
  *
+ * The active recording for an execution lives in `AsyncLocalStorage`, so each (possibly nested) circuit execution owns
+ * its own recording and concurrent or re-entrant executions cannot corrupt one another's state. Nested executions
+ * (`aztec_prv_callPrivateFunction`, utility calls) re-enter {@link record}, which links the child to the recording
+ * active in the enclosing async context and lets ALS restore the parent automatically when the child completes.
+ *
  * Example recording object:
  * ```json
  * {
@@ -68,27 +74,38 @@ export class CircuitRecording {
  * ```
  */ export class CircuitRecorder {
     logger;
-    recording;
-    stackDepth = 0;
-    newCircuit = true;
+    #recordings = new AsyncLocalStorage();
     constructor(loggerOrBindings){
         this.logger = resolveLogger('simulator:acvm:recording', loggerOrBindings);
     }
     /**
-   * Initializes a new circuit recording session.
-   * @param recordDir - Directory to store the recording
-   * @param input - Circuit input witness
-   * @param circuitBytecode - Compiled circuit bytecode
-   * @param circuitName - Name of the circuit
-   * @param functionName - Name of the circuit function (defaults to 'main'). This is meaningful only for
-   * contracts as protocol circuits artifacts always contain a single entrypoint function called 'main'.
-   */ start(input, circuitBytecode, circuitName, functionName) {
-        if (this.newCircuit) {
-            const parentRef = this.recording;
-            this.recording = new CircuitRecording(circuitName, functionName, sha512(circuitBytecode).toString('hex'), Object.fromEntries(input));
-            this.recording.setParent(parentRef);
-        }
-        return Promise.resolve();
+   * Records a single circuit execution. Opens a recording for the circuit (linked as a child of the recording active
+   * in the current async context, if any), runs `fn` within that recording's context, and finalizes it. The recording
+   * is returned alongside the result so callers can derive per-circuit stats (e.g. oracle timings).
+   *
+   * Recorder bookkeeping never alters execution: if `fn` throws, the error is attached to the recording and re-thrown
+   * unchanged.
+   * @param metadata - Identifies the circuit and its initial witness.
+   * @param fn - Runs the circuit execution; its oracle calls are recorded into this recording.
+   */ record(metadata, fn) {
+        const parent = this.#recordings.getStore();
+        const recording = new CircuitRecording(metadata.circuitName, metadata.functionName, sha512(metadata.bytecode).toString('hex'), Object.fromEntries(metadata.input));
+        recording.setParent(parent);
+        return this.#recordings.run(recording, async ()=>{
+            await this.onStart(recording);
+            try {
+                const result = await fn();
+                await this.onFinish(recording);
+                return {
+                    result,
+                    recording
+                };
+            } catch (error) {
+                recording.error = JSON.stringify(error);
+                await this.onError(recording, error);
+                throw error;
+            }
+        });
     }
     /**
    * Wraps a callback to record all oracle/foreign calls.
@@ -109,7 +126,9 @@ export class CircuitRecording {
         return typeof callback === 'object' && callback !== null && !('call' in callback);
     }
     /**
-   * Wraps a user circuit callback to record all oracle calls.
+   * Wraps a user circuit callback to record all oracle calls. A nested circuit entered via an oracle (e.g.
+   * `aztec_prv_callPrivateFunction`) re-enters {@link record}, so its own oracle calls land on the child recording and
+   * this circuit's calls (including the entering oracle call itself) land on this recording once the child completes.
    * @param callback - The original circuit callback.
    * @returns A wrapped callback that records all oracle interactions which is to be provided to the ACVM.
    */ #wrapUserCircuitCallback(callback) {
@@ -120,37 +139,16 @@ export class CircuitRecording {
             if (!fn || typeof fn !== 'function') {
                 throw new Error(`Oracle method ${name} not found when setting up recording callback`);
             }
-            const isExternalCall = name === 'aztec_prv_callPrivateFunction';
             recordingCallback[name] = (...args)=>{
                 const timer = new Timer();
-                // If we're entering another circuit via `aztec_prv_callPrivateFunction`, we increase the stack depth and set the
-                // newCircuit variable to ensure we are creating a new recording object.
-                if (isExternalCall) {
-                    this.stackDepth++;
-                    this.newCircuit = true;
-                }
                 const result = fn.call(callback, ...args);
                 if (result instanceof Promise) {
                     return result.then(async (r)=>{
-                        // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
-                        // so that the parent circuit continues with its existing recording
-                        // Note: recording restoration is handled by finish()
-                        if (isExternalCall) {
-                            this.stackDepth--;
-                            this.newCircuit = false;
-                        }
-                        await this.recordCall(name, args, r, timer.ms(), this.stackDepth);
+                        await this.recordCall(name, args, r, timer.ms());
                         return r;
                     });
                 }
-                // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
-                // so that the parent circuit continues with its existing recording
-                // Note: recording restoration is handled by finish()
-                if (isExternalCall) {
-                    this.stackDepth--;
-                    this.newCircuit = false;
-                }
-                void this.recordCall(name, args, result, timer.ms(), this.stackDepth);
+                void this.recordCall(name, args, result, timer.ms());
                 return result;
             };
         }
@@ -164,49 +162,47 @@ export class CircuitRecording {
         return async (name, inputs)=>{
             const timer = new Timer();
             const result = await callback(name, inputs);
-            await this.recordCall(name, inputs, result, timer.ms(), 0);
+            await this.recordCall(name, inputs, result, timer.ms());
             return result;
         };
     }
     /**
-   * Records a single oracle/foreign call with its inputs and outputs.
+   * Records a single oracle/foreign call with its inputs and outputs against the recording active in the current
+   * async context.
    * @param name - Name of the call
    * @param inputs - Input arguments
    * @param outputs - Output results
-   */ recordCall(name, inputs, outputs, time, stackDepth) {
+   */ recordCall(name, inputs, outputs, time) {
+        const recording = this.#recordings.getStore();
         const entry = {
             name,
             inputs,
             outputs,
             time,
-            stackDepth
+            stackDepth: depthOf(recording)
         };
-        this.recording.oracleCalls.push(entry);
+        // Outside any active recording context (e.g. a stray call after the scope closed, or a direct unit-test call)
+        // there is nowhere to record; return the entry without throwing into the execution path.
+        recording?.oracleCalls.push(entry);
         return Promise.resolve(entry);
     }
-    /**
-   * Finalizes the recording by resetting the state and returning the recording object.
-   */ finish() {
-        const result = this.recording;
-        // If this is the top-level circuit recording, we reset the state for the next simulator call
-        if (!result.parent) {
-            this.newCircuit = true;
-            this.recording = undefined;
-        } else {
-            // For nested circuits (utility calls, nested contract calls), restore to parent recording
-            // Note: we don't set newCircuit=false here because:
-            // - For privateCallPrivateFunction, the callback wrapper will set it to false
-            // - For utility calls, we want newCircuit to remain true so the next circuit creates its own recording
-            this.recording = result.parent;
-        }
-        return Promise.resolve(result);
+    /** The recording active in the current async context, if any. */ currentRecording() {
+        return this.#recordings.getStore();
     }
-    /**
-   * Finalizes the recording by resetting the state and returning the recording object with an attached error.
-   * @param error - The error that occurred during circuit execution
-   */ async finishWithError(error) {
-        const result = await this.finish();
-        result.error = JSON.stringify(error);
-        return result;
+    /** Hook invoked when a recording opens, within the recording's context. Overridden to persist recordings. */ onStart(_recording) {
+        return Promise.resolve();
+    }
+    /** Hook invoked when a recording completes successfully, within the recording's context. */ onFinish(_recording) {
+        return Promise.resolve();
+    }
+    /** Hook invoked when a recording's execution throws, within the recording's context. */ onError(_recording, _error) {
+        return Promise.resolve();
+    }
+}
+/** Depth of a recording in the call tree: 0 for a top-level circuit, incremented per nested circuit. */ function depthOf(recording) {
+    let depth = 0;
+    for(let ancestor = recording?.parent; ancestor; ancestor = ancestor.parent){
+        depth++;
     }
+    return depth;
 }

package/dest/private/circuit_recording/file_circuit_recorder.d.ts

@@ -1,32 +1,20 @@
 import type { Logger } from '@aztec/foundation/log';
-import type { ACVMWitness } from '../acvm/acvm_types.js';
 import { CircuitRecorder, type CircuitRecording } from './circuit_recorder.js';
 export declare class FileCircuitRecorder extends CircuitRecorder {
     #private;
     private readonly recordDir;
-    recording?: CircuitRecording & {
-        filePath: string;
-        isFirstCall: boolean;
-    };
     constructor(recordDir: string, logger?: Logger);
-    start(input: ACVMWitness, circuitBytecode: Buffer, circuitName: string, functionName?: string): Promise<void>;
+    protected onStart(recording: CircuitRecording): Promise<void>;
     /**
      * Records a single oracle/foreign call with its inputs and outputs.
      * @param name - Name of the call
      * @param inputs - Input arguments
      * @param outputs - Output results
      */
-    recordCall(name: string, inputs: unknown[], outputs: unknown, time: number, stackDepth: number): Promise<import("./circuit_recorder.js").OracleCall>;
-    /**
-     * Finalizes the recording file by adding closing brackets. Without calling this method, the recording file is
-     * incomplete and it fails to parse.
-     */
-    finish(): Promise<CircuitRecording>;
-    /**
-     * Finalizes the recording file by adding the error and closing brackets. Without calling this method or `finish`,
-     * the recording file is incomplete and it fails to parse.
-     * @param error - The error that occurred during circuit execution
-     */
-    finishWithError(error: unknown): Promise<CircuitRecording>;
+    recordCall(name: string, inputs: unknown[], outputs: unknown, time: number): Promise<import("./circuit_recorder.js").OracleCall>;
+    /** Closes the recording file with the trailing brackets so the JSON parses. */
+    protected onFinish(recording: CircuitRecording): Promise<void>;
+    /** Closes the recording file with the execution error and trailing brackets so the JSON parses. */
+    protected onError(recording: CircuitRecording, error: unknown): Promise<void>;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmlsZV9jaXJjdWl0X3JlY29yZGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvcHJpdmF0ZS9jaXJjdWl0X3JlY29yZGluZy9maWxlX2NpcmN1aXRfcmVjb3JkZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsTUFBTSxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFLcEQsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFDekQsT0FBTyxFQUFFLGVBQWUsRUFBRSxLQUFLLGdCQUFnQixFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFFL0UscUJBQWEsbUJBQW9CLFNBQVEsZUFBZTs7SUFJcEQsT0FBTyxDQUFDLFFBQVEsQ0FBQyxTQUFTO0lBSHBCLFNBQVMsQ0FBQyxFQUFFLGdCQUFnQixHQUFHO1FBQUUsUUFBUSxFQUFFLE1BQU0sQ0FBQztRQUFDLFdBQVcsRUFBRSxPQUFPLENBQUE7S0FBRSxDQUFDO0lBRWxGLFlBQ21CLFNBQVMsRUFBRSxNQUFNLEVBQ2xDLE1BQU0sQ0FBQyxFQUFFLE1BQU0sRUFHaEI7SUFFYyxLQUFLLENBQ2xCLEtBQUssRUFBRSxXQUFXLEVBQ2xCLGVBQWUsRUFBRSxNQUFNLEVBQ3ZCLFdBQVcsRUFBRSxNQUFNLEVBQ25CLFlBQVksR0FBRSxNQUFlLGlCQWdDOUI7SUFxQ0Q7Ozs7O09BS0c7SUFDWSxVQUFVLENBQUMsSUFBSSxFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFLEVBQUUsT0FBTyxFQUFFLE9BQU8sRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLFVBQVUsRUFBRSxNQUFNLHVEQVU1RztJQUVEOzs7T0FHRztJQUNZLE1BQU0sSUFBSSxPQUFPLENBQUMsZ0JBQWdCLENBQUMsQ0FXakQ7SUFFRDs7OztPQUlHO0lBQ1ksZUFBZSxDQUFDLEtBQUssRUFBRSxPQUFPLEdBQUcsT0FBTyxDQUFDLGdCQUFnQixDQUFDLENBYXhFO0NBQ0YifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmlsZV9jaXJjdWl0X3JlY29yZGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvcHJpdmF0ZS9jaXJjdWl0X3JlY29yZGluZy9maWxlX2NpcmN1aXRfcmVjb3JkZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsTUFBTSxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFLcEQsT0FBTyxFQUFFLGVBQWUsRUFBRSxLQUFLLGdCQUFnQixFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFLL0UscUJBQWEsbUJBQW9CLFNBQVEsZUFBZTs7SUFJcEQsT0FBTyxDQUFDLFFBQVEsQ0FBQyxTQUFTO0lBRDVCLFlBQ21CLFNBQVMsRUFBRSxNQUFNLEVBQ2xDLE1BQU0sQ0FBQyxFQUFFLE1BQU0sRUFHaEI7SUFFRCxVQUF5QixPQUFPLENBQUMsU0FBUyxFQUFFLGdCQUFnQixHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0E2QjNFO0lBcUNEOzs7OztPQUtHO0lBQ1ksVUFBVSxDQUFDLElBQUksRUFBRSxNQUFNLEVBQUUsTUFBTSxFQUFFLE9BQU8sRUFBRSxFQUFFLE9BQU8sRUFBRSxPQUFPLEVBQUUsSUFBSSxFQUFFLE1BQU0sdURBY3hGO0lBRUQsK0VBQStFO0lBQy9FLFVBQXlCLFFBQVEsQ0FBQyxTQUFTLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQVU1RTtJQUVELG1HQUFtRztJQUNuRyxVQUF5QixPQUFPLENBQUMsU0FBUyxFQUFFLGdCQUFnQixFQUFFLEtBQUssRUFBRSxPQUFPLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQVkzRjtDQUNGIn0=

package/dest/private/circuit_recording/file_circuit_recorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file_circuit_recorder.d.ts","sourceRoot":"","sources":["../../../src/private/circuit_recording/file_circuit_recorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAKpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE/E,qBAAa,mBAAoB,SAAQ,eAAe;;IAIpD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAHpB,SAAS,CAAC,EAAE,gBAAgB,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;IAElF,YACmB,SAAS,EAAE,MAAM,EAClC,MAAM,CAAC,EAAE,MAAM,EAGhB;IAEc,KAAK,CAClB,KAAK,EAAE,WAAW,EAClB,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,YAAY,GAAE,MAAe,iBAgC9B;IAqCD;;;;;OAKG;IACY,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,uDAU5G;IAED;;;OAGG;IACY,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAWjD;IAED;;;;OAIG;IACY,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAaxE;CACF"}
+{"version":3,"file":"file_circuit_recorder.d.ts","sourceRoot":"","sources":["../../../src/private/circuit_recording/file_circuit_recorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAKpD,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAK/E,qBAAa,mBAAoB,SAAQ,eAAe;;IAIpD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAD5B,YACmB,SAAS,EAAE,MAAM,EAClC,MAAM,CAAC,EAAE,MAAM,EAGhB;IAED,UAAyB,OAAO,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B3E;IAqCD;;;;;OAKG;IACY,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,uDAcxF;IAED,+EAA+E;IAC/E,UAAyB,QAAQ,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5E;IAED,mGAAmG;IACnG,UAAyB,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAY3F;CACF"}

package/dest/private/circuit_recording/file_circuit_recorder.js

@@ -3,17 +3,15 @@ import path from 'path';
 import { CircuitRecorder } from './circuit_recorder.js';
 export class FileCircuitRecorder extends CircuitRecorder {
     recordDir;
+    #fileState;
     constructor(recordDir, logger){
-        super(logger), this.recordDir = recordDir;
+        super(logger), this.recordDir = recordDir, this.#fileState = new WeakMap();
     }
-    async start(input, circuitBytecode, circuitName, functionName = 'main') {
-        await super.start(input, circuitBytecode, circuitName, functionName);
+    async onStart(recording) {
         const recordingStringWithoutClosingBracket = JSON.stringify({
-            ...this.recording,
-            isFirstCall: undefined,
+            ...recording,
             parent: undefined,
-            oracleCalls: undefined,
-            filePath: undefined
+            oracleCalls: undefined
         }, null, 2).slice(0, -2);
         try {
             // Check if the recording directory exists and is a directory
@@ -31,8 +29,11 @@ export class FileCircuitRecorder extends CircuitRecorder {
                 throw err;
             }
         }
-        this.recording.isFirstCall = true;
-        this.recording.filePath = await FileCircuitRecorder.#computeFilePathAndStoreInitialRecording(this.recordDir, this.recording.circuitName, this.recording.functionName, recordingStringWithoutClosingBracket);
+        const filePath = await FileCircuitRecorder.#computeFilePathAndStoreInitialRecording(this.recordDir, recording.circuitName, recording.functionName, recordingStringWithoutClosingBracket);
+        this.#fileState.set(recording, {
+            filePath,
+            isFirstCall: true
+        });
     }
     /**
    * Computes a unique file path for the recording by trying different counter values.
@@ -67,55 +68,50 @@ export class FileCircuitRecorder extends CircuitRecorder {
    * @param name - Name of the call
    * @param inputs - Input arguments
    * @param outputs - Output results
-   */ async recordCall(name, inputs, outputs, time, stackDepth) {
-        const entry = await super.recordCall(name, inputs, outputs, time, stackDepth);
-        try {
-            const prefix = this.recording.isFirstCall ? '    ' : '    ,';
-            this.recording.isFirstCall = false;
-            await fs.appendFile(this.recording.filePath, prefix + JSON.stringify(entry) + '\n');
-        } catch (err) {
-            this.logger.error('Failed to log circuit call', {
-                error: err
-            });
+   */ async recordCall(name, inputs, outputs, time) {
+        const entry = await super.recordCall(name, inputs, outputs, time);
+        const recording = this.currentRecording();
+        const state = recording && this.#fileState.get(recording);
+        if (state) {
+            try {
+                const prefix = state.isFirstCall ? '    ' : '    ,';
+                state.isFirstCall = false;
+                await fs.appendFile(state.filePath, prefix + JSON.stringify(entry) + '\n');
+            } catch (err) {
+                this.logger.error('Failed to log circuit call', {
+                    error: err
+                });
+            }
         }
         return entry;
     }
-    /**
-   * Finalizes the recording file by adding closing brackets. Without calling this method, the recording file is
-   * incomplete and it fails to parse.
-   */ async finish() {
-        // Finish sets the recording to undefined if we are at the topmost circuit,
-        // so we save the current file path before that
-        const filePath = this.recording.filePath;
-        const result = await super.finish();
+    /** Closes the recording file with the trailing brackets so the JSON parses. */ async onFinish(recording) {
+        const state = this.#fileState.get(recording);
+        if (!state) {
+            return;
+        }
         try {
-            await fs.appendFile(filePath, '  ]\n}\n');
+            await fs.appendFile(state.filePath, '  ]\n}\n');
         } catch (err) {
             this.logger.error('Failed to finalize recording file', {
                 error: err
             });
         }
-        return result;
     }
-    /**
-   * Finalizes the recording file by adding the error and closing brackets. Without calling this method or `finish`,
-   * the recording file is incomplete and it fails to parse.
-   * @param error - The error that occurred during circuit execution
-   */ async finishWithError(error) {
-        // Finish sets the recording to undefined if we are at the topmost circuit,
-        // so we save the current file path before that
-        const filePath = this.recording.filePath;
-        const result = await super.finishWithError(error);
+    /** Closes the recording file with the execution error and trailing brackets so the JSON parses. */ async onError(recording, error) {
+        const state = this.#fileState.get(recording);
+        if (!state) {
+            return;
+        }
         try {
-            await fs.appendFile(filePath, '  ],\n');
-            await fs.appendFile(filePath, `  "error": ${JSON.stringify(error)}\n`);
-            await fs.appendFile(filePath, '}\n');
+            await fs.appendFile(state.filePath, '  ],\n');
+            await fs.appendFile(state.filePath, `  "error": ${JSON.stringify(error)}\n`);
+            await fs.appendFile(state.filePath, '}\n');
         } catch (err) {
             this.logger.error('Failed to finalize recording file with error', {
                 error: err
             });
         }
-        return result;
     }
 }
 /**

package/dest/private/circuit_recording/simulator_recorder_wrapper.d.ts

@@ -18,4 +18,4 @@ export declare class SimulatorRecorderWrapper implements CircuitSimulator {
     executeProtocolCircuit(input: ACVMWitness, artifact: NoirCompiledCircuitWithName, callback: ForeignCallHandler | undefined): Promise<ACVMSuccess>;
     executeUserCircuit(input: ACVMWitness, artifact: FunctionArtifactWithContractName, callback: ACIRCallback): Promise<ACIRExecutionResult>;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2ltdWxhdG9yX3JlY29yZGVyX3dyYXBwZXIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9wcml2YXRlL2NpcmN1aXRfcmVjb3JkaW5nL3NpbXVsYXRvcl9yZWNvcmRlcl93cmFwcGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGtCQUFrQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDOUQsT0FBTyxLQUFLLEVBQUUsZ0NBQWdDLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUMxRSxPQUFPLEtBQUssRUFBRSwyQkFBMkIsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBRXRFLE9BQU8sS0FBSyxFQUFFLFlBQVksRUFBcUIsbUJBQW1CLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUM1RixPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUN6RCxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUNyRCxPQUFPLEtBQUssRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQ2hFLE9BQU8sS0FBSyxFQUFFLGVBQWUsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRTdEOzs7R0FHRztBQUNILHFCQUFhLHdCQUF5QixZQUFXLGdCQUFnQjs7SUFFN0QsT0FBTyxDQUFDLFNBQVM7SUFDakIsT0FBTyxDQUFDLFFBQVE7SUFGbEIsWUFDVSxTQUFTLEVBQUUsZ0JBQWdCLEVBQzNCLFFBQVEsRUFBRSxlQUFlLEVBQy9CO0lBRUosc0JBQXNCLENBQ3BCLEtBQUssRUFBRSxXQUFXLEVBQ2xCLFFBQVEsRUFBRSwyQkFBMkIsRUFDckMsUUFBUSxFQUFFLGtCQUFrQixHQUFHLFNBQVMsR0FDdkMsT0FBTyxDQUFDLFdBQVcsQ0FBQyxDQVd0QjtJQUVELGtCQUFrQixDQUNoQixLQUFLLEVBQUUsV0FBVyxFQUNsQixRQUFRLEVBQUUsZ0NBQWdDLEVBQzFDLFFBQVEsRUFBRSxZQUFZLEdBQ3JCLE9BQU8sQ0FBQyxtQkFBbUIsQ0FBQyxDQVM5QjtDQXdDRiJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2ltdWxhdG9yX3JlY29yZGVyX3dyYXBwZXIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9wcml2YXRlL2NpcmN1aXRfcmVjb3JkaW5nL3NpbXVsYXRvcl9yZWNvcmRlcl93cmFwcGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGtCQUFrQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDOUQsT0FBTyxLQUFLLEVBQUUsZ0NBQWdDLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUMxRSxPQUFPLEtBQUssRUFBRSwyQkFBMkIsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBRXRFLE9BQU8sS0FBSyxFQUFFLFlBQVksRUFBcUIsbUJBQW1CLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUM1RixPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUN6RCxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUNyRCxPQUFPLEtBQUssRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQ2hFLE9BQU8sS0FBSyxFQUFFLGVBQWUsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRTdEOzs7R0FHRztBQUNILHFCQUFhLHdCQUF5QixZQUFXLGdCQUFnQjs7SUFFN0QsT0FBTyxDQUFDLFNBQVM7SUFDakIsT0FBTyxDQUFDLFFBQVE7SUFGbEIsWUFDVSxTQUFTLEVBQUUsZ0JBQWdCLEVBQzNCLFFBQVEsRUFBRSxlQUFlLEVBQy9CO0lBRUosc0JBQXNCLENBQ3BCLEtBQUssRUFBRSxXQUFXLEVBQ2xCLFFBQVEsRUFBRSwyQkFBMkIsRUFDckMsUUFBUSxFQUFFLGtCQUFrQixHQUFHLFNBQVMsR0FDdkMsT0FBTyxDQUFDLFdBQVcsQ0FBQyxDQVd0QjtJQUVELGtCQUFrQixDQUNoQixLQUFLLEVBQUUsV0FBVyxFQUNsQixRQUFRLEVBQUUsZ0NBQWdDLEVBQzFDLFFBQVEsRUFBRSxZQUFZLEdBQ3JCLE9BQU8sQ0FBQyxtQkFBbUIsQ0FBQyxDQVM5QjtDQWtDRiJ9

package/dest/private/circuit_recording/simulator_recorder_wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simulator_recorder_wrapper.d.ts","sourceRoot":"","sources":["../../../src/private/circuit_recording/simulator_recorder_wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,KAAK,EAAE,YAAY,EAAqB,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;;IAE7D,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,QAAQ;IAFlB,YACU,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,EAAE,eAAe,EAC/B;IAEJ,sBAAsB,CACpB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,2BAA2B,EACrC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GACvC,OAAO,CAAC,WAAW,CAAC,CAWtB;IAED,kBAAkB,CAChB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,gCAAgC,EAC1C,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,mBAAmB,CAAC,CAS9B;CAwCF"}
+{"version":3,"file":"simulator_recorder_wrapper.d.ts","sourceRoot":"","sources":["../../../src/private/circuit_recording/simulator_recorder_wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,KAAK,EAAE,YAAY,EAAqB,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;;IAE7D,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,QAAQ;IAFlB,YACU,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,EAAE,eAAe,EAC/B;IAEJ,sBAAsB,CACpB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,2BAA2B,EACrC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GACvC,OAAO,CAAC,WAAW,CAAC,CAWtB;IAED,kBAAkB,CAChB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,gCAAgC,EAC1C,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,mBAAmB,CAAC,CAS9B;CAkCF"}

package/dest/private/circuit_recording/simulator_recorder_wrapper.js

@@ -16,21 +16,18 @@
         return this.#simulate((wrappedCallback)=>this.simulator.executeUserCircuit(input, artifact, wrappedCallback), input, artifact.bytecode, artifact.contractName, artifact.name, callback);
     }
     async #simulate(simulateFn, input, bytecode, contractName, functionName, callback) {
-        // Start recording circuit execution
-        await this.recorder.start(input, bytecode, contractName, functionName);
-        // If callback was provided, we wrap it in a circuit recorder callback wrapper
+        // If a callback was provided, we wrap it so that its oracle calls are recorded. The wrapped callback reads the
+        // active recording lazily, so it picks up the recording opened by record() below.
         const wrappedCallback = this.recorder.wrapCallback(callback);
-        let result;
-        try {
-            result = await simulateFn(wrappedCallback);
-        } catch (error) {
-            // If an error occurs, we finalize the recording file with the error
-            await this.recorder.finishWithError(error);
-            throw error;
-        }
-        // Witness generation is complete so we finish the circuit recorder
-        const recording = await this.recorder.finish();
-        result.oracles = recording.oracleCalls?.reduce((acc, { time, name })=>{
+        // record() opens a recording for this circuit, runs the simulation within it, and finalizes it. A simulation
+        // failure is re-thrown unchanged, so recorder bookkeeping never masks the underlying error.
+        const { result, recording } = await this.recorder.record({
+            input,
+            bytecode,
+            circuitName: contractName,
+            functionName
+        }, ()=>simulateFn(wrappedCallback));
+        result.oracles = recording.oracleCalls.reduce((acc, { time, name })=>{
             if (!acc[name]) {
                 acc[name] = {
                     times: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/simulator",
-  "version": "5.0.0-nightly.20260616",
+  "version": "5.0.0-nightly.20260618",
   "type": "module",
   "exports": {
     "./server": "./dest/server.js",
@@ -64,26 +64,26 @@
     ]
   },
   "dependencies": {
-    "@aztec/constants": "5.0.0-nightly.20260616",
-    "@aztec/foundation": "5.0.0-nightly.20260616",
-    "@aztec/native": "5.0.0-nightly.20260616",
-    "@aztec/noir-acvm_js": "5.0.0-nightly.20260616",
-    "@aztec/noir-noirc_abi": "5.0.0-nightly.20260616",
-    "@aztec/noir-protocol-circuits-types": "5.0.0-nightly.20260616",
-    "@aztec/noir-types": "5.0.0-nightly.20260616",
-    "@aztec/protocol-contracts": "5.0.0-nightly.20260616",
-    "@aztec/standard-contracts": "5.0.0-nightly.20260616",
-    "@aztec/stdlib": "5.0.0-nightly.20260616",
-    "@aztec/telemetry-client": "5.0.0-nightly.20260616",
-    "@aztec/world-state": "5.0.0-nightly.20260616",
+    "@aztec/constants": "5.0.0-nightly.20260618",
+    "@aztec/foundation": "5.0.0-nightly.20260618",
+    "@aztec/native": "5.0.0-nightly.20260618",
+    "@aztec/noir-acvm_js": "5.0.0-nightly.20260618",
+    "@aztec/noir-noirc_abi": "5.0.0-nightly.20260618",
+    "@aztec/noir-protocol-circuits-types": "5.0.0-nightly.20260618",
+    "@aztec/noir-types": "5.0.0-nightly.20260618",
+    "@aztec/protocol-contracts": "5.0.0-nightly.20260618",
+    "@aztec/standard-contracts": "5.0.0-nightly.20260618",
+    "@aztec/stdlib": "5.0.0-nightly.20260618",
+    "@aztec/telemetry-client": "5.0.0-nightly.20260618",
+    "@aztec/world-state": "5.0.0-nightly.20260618",
     "lodash.clonedeep": "^4.5.0",
     "lodash.merge": "^4.6.2",
     "tslib": "^2.4.0"
   },
   "devDependencies": {
-    "@aztec/kv-store": "5.0.0-nightly.20260616",
-    "@aztec/noir-contracts.js": "5.0.0-nightly.20260616",
-    "@aztec/noir-test-contracts.js": "5.0.0-nightly.20260616",
+    "@aztec/kv-store": "5.0.0-nightly.20260618",
+    "@aztec/noir-contracts.js": "5.0.0-nightly.20260618",
+    "@aztec/noir-test-contracts.js": "5.0.0-nightly.20260618",
     "@jest/globals": "^30.0.0",
     "@types/jest": "^30.0.0",
     "@types/lodash.clonedeep": "^4.5.7",

package/src/client.ts

@@ -1,6 +1,4 @@
 export * from './private/acvm/index.js';
 export { WASMSimulator } from './private/acvm_wasm.js';
-export { SimulatorRecorderWrapper } from './private/circuit_recording/simulator_recorder_wrapper.js';
-export { MemoryCircuitRecorder } from './private/circuit_recording/memory_circuit_recorder.js';
 export { type CircuitSimulator, type DecodedError } from './private/circuit_simulator.js';
 export * from './common/index.js';

package/src/private/circuit_recording/circuit_recorder.ts

@@ -3,6 +3,8 @@ import { type Logger, type LoggerBindings, resolveLogger } from '@aztec/foundati
 import { Timer } from '@aztec/foundation/timer';
 import type { ForeignCallHandler, ForeignCallInput, ForeignCallOutput } from '@aztec/noir-acvm_js';
 
+import { AsyncLocalStorage } from 'node:async_hooks';
+
 import type { ACIRCallback } from '../acvm/acvm.js';
 import type { ACVMWitness } from '../acvm/acvm_types.js';
 
@@ -43,10 +45,23 @@ export class CircuitRecording {
   }
 }
 
+/** Inputs needed to open a recording for a single circuit execution. */
+export type RecordingMetadata = {
+  input: ACVMWitness;
+  bytecode: Buffer;
+  circuitName: string;
+  functionName: string;
+};
+
 /**
  * Class responsible for recording circuit inputs necessary to replay the circuit. These inputs are the initial witness
  * map and the oracle calls made during the circuit execution/witness generation.
  *
+ * The active recording for an execution lives in `AsyncLocalStorage`, so each (possibly nested) circuit execution owns
+ * its own recording and concurrent or re-entrant executions cannot corrupt one another's state. Nested executions
+ * (`aztec_prv_callPrivateFunction`, utility calls) re-enter {@link record}, which links the child to the recording
+ * active in the enclosing async context and lets ALS restore the parent automatically when the child completes.
+ *
  * Example recording object:
  * ```json
  * {
@@ -91,37 +106,44 @@ export class CircuitRecording {
 export class CircuitRecorder {
   protected readonly logger: Logger;
 
-  protected recording?: CircuitRecording;
-
-  private stackDepth: number = 0;
-  private newCircuit: boolean = true;
+  readonly #recordings = new AsyncLocalStorage<CircuitRecording>();
 
   protected constructor(loggerOrBindings?: Logger | LoggerBindings) {
     this.logger = resolveLogger('simulator:acvm:recording', loggerOrBindings);
   }
 
   /**
-   * Initializes a new circuit recording session.
-   * @param recordDir - Directory to store the recording
-   * @param input - Circuit input witness
-   * @param circuitBytecode - Compiled circuit bytecode
-   * @param circuitName - Name of the circuit
-   * @param functionName - Name of the circuit function (defaults to 'main'). This is meaningful only for
-   * contracts as protocol circuits artifacts always contain a single entrypoint function called 'main'.
+   * Records a single circuit execution. Opens a recording for the circuit (linked as a child of the recording active
+   * in the current async context, if any), runs `fn` within that recording's context, and finalizes it. The recording
+   * is returned alongside the result so callers can derive per-circuit stats (e.g. oracle timings).
+   *
+   * Recorder bookkeeping never alters execution: if `fn` throws, the error is attached to the recording and re-thrown
+   * unchanged.
+   * @param metadata - Identifies the circuit and its initial witness.
+   * @param fn - Runs the circuit execution; its oracle calls are recorded into this recording.
    */
-  start(input: ACVMWitness, circuitBytecode: Buffer, circuitName: string, functionName: string): Promise<void> {
-    if (this.newCircuit) {
-      const parentRef = this.recording;
-      this.recording = new CircuitRecording(
-        circuitName,
-        functionName,
-        sha512(circuitBytecode).toString('hex'),
-        Object.fromEntries(input),
-      );
-      this.recording.setParent(parentRef);
-    }
+  record<T>(metadata: RecordingMetadata, fn: () => Promise<T>): Promise<{ result: T; recording: CircuitRecording }> {
+    const parent = this.#recordings.getStore();
+    const recording = new CircuitRecording(
+      metadata.circuitName,
+      metadata.functionName,
+      sha512(metadata.bytecode).toString('hex'),
+      Object.fromEntries(metadata.input),
+    );
+    recording.setParent(parent);
 
-    return Promise.resolve();
+    return this.#recordings.run(recording, async () => {
+      await this.onStart(recording);
+      try {
+        const result = await fn();
+        await this.onFinish(recording);
+        return { result, recording };
+      } catch (error) {
+        recording.error = JSON.stringify(error);
+        await this.onError(recording, error);
+        throw error;
+      }
+    });
   }
 
   /**
@@ -147,7 +169,9 @@ export class CircuitRecorder {
   }
 
   /**
-   * Wraps a user circuit callback to record all oracle calls.
+   * Wraps a user circuit callback to record all oracle calls. A nested circuit entered via an oracle (e.g.
+   * `aztec_prv_callPrivateFunction`) re-enters {@link record}, so its own oracle calls land on the child recording and
+   * this circuit's calls (including the entering oracle call itself) land on this recording once the child completes.
    * @param callback - The original circuit callback.
    * @returns A wrapped callback that records all oracle interactions which is to be provided to the ACVM.
    */
@@ -161,38 +185,16 @@ export class CircuitRecorder {
         throw new Error(`Oracle method ${name} not found when setting up recording callback`);
       }
 
-      const isExternalCall = (name as keyof ACIRCallback) === 'aztec_prv_callPrivateFunction';
-
       recordingCallback[name as keyof ACIRCallback] = (...args: ForeignCallInput[]): ReturnType<typeof fn> => {
         const timer = new Timer();
-        // If we're entering another circuit via `aztec_prv_callPrivateFunction`, we increase the stack depth and set the
-        // newCircuit variable to ensure we are creating a new recording object.
-        if (isExternalCall) {
-          this.stackDepth++;
-          this.newCircuit = true;
-        }
         const result = fn.call(callback, ...args);
         if (result instanceof Promise) {
           return result.then(async r => {
-            // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
-            // so that the parent circuit continues with its existing recording
-            // Note: recording restoration is handled by finish()
-            if (isExternalCall) {
-              this.stackDepth--;
-              this.newCircuit = false;
-            }
-            await this.recordCall(name, args, r, timer.ms(), this.stackDepth);
+            await this.recordCall(name, args, r, timer.ms());
             return r;
           }) as ReturnType<typeof fn>;
         }
-        // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
-        // so that the parent circuit continues with its existing recording
-        // Note: recording restoration is handled by finish()
-        if (isExternalCall) {
-          this.stackDepth--;
-          this.newCircuit = false;
-        }
-        void this.recordCall(name, args, result, timer.ms(), this.stackDepth);
+        void this.recordCall(name, args, result, timer.ms());
         return result;
       };
     }
@@ -209,55 +211,59 @@ export class CircuitRecorder {
     return async (name: string, inputs: ForeignCallInput[]): Promise<ForeignCallOutput[]> => {
       const timer = new Timer();
       const result = await callback(name, inputs);
-      await this.recordCall(name, inputs, result, timer.ms(), 0);
+      await this.recordCall(name, inputs, result, timer.ms());
       return result;
     };
   }
 
   /**
-   * Records a single oracle/foreign call with its inputs and outputs.
+   * Records a single oracle/foreign call with its inputs and outputs against the recording active in the current
+   * async context.
    * @param name - Name of the call
    * @param inputs - Input arguments
    * @param outputs - Output results
    */
-  recordCall(name: string, inputs: unknown[], outputs: unknown, time: number, stackDepth: number): Promise<OracleCall> {
+  recordCall(name: string, inputs: unknown[], outputs: unknown, time: number): Promise<OracleCall> {
+    const recording = this.#recordings.getStore();
     const entry = {
       name,
       inputs,
       outputs,
       time,
-      stackDepth,
+      stackDepth: depthOf(recording),
     };
-    this.recording!.oracleCalls.push(entry);
+    // Outside any active recording context (e.g. a stray call after the scope closed, or a direct unit-test call)
+    // there is nowhere to record; return the entry without throwing into the execution path.
+    recording?.oracleCalls.push(entry);
     return Promise.resolve(entry);
   }
 
-  /**
-   * Finalizes the recording by resetting the state and returning the recording object.
-   */
-  finish(): Promise<CircuitRecording> {
-    const result = this.recording;
-    // If this is the top-level circuit recording, we reset the state for the next simulator call
-    if (!result!.parent) {
-      this.newCircuit = true;
-      this.recording = undefined;
-    } else {
-      // For nested circuits (utility calls, nested contract calls), restore to parent recording
-      // Note: we don't set newCircuit=false here because:
-      // - For privateCallPrivateFunction, the callback wrapper will set it to false
-      // - For utility calls, we want newCircuit to remain true so the next circuit creates its own recording
-      this.recording = result!.parent;
-    }
-    return Promise.resolve(result!);
+  /** The recording active in the current async context, if any. */
+  protected currentRecording(): CircuitRecording | undefined {
+    return this.#recordings.getStore();
   }
 
-  /**
-   * Finalizes the recording by resetting the state and returning the recording object with an attached error.
-   * @param error - The error that occurred during circuit execution
-   */
-  async finishWithError(error: unknown): Promise<CircuitRecording> {
-    const result = await this.finish();
-    result.error = JSON.stringify(error);
-    return result;
+  /** Hook invoked when a recording opens, within the recording's context. Overridden to persist recordings. */
+  protected onStart(_recording: CircuitRecording): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /** Hook invoked when a recording completes successfully, within the recording's context. */
+  protected onFinish(_recording: CircuitRecording): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /** Hook invoked when a recording's execution throws, within the recording's context. */
+  protected onError(_recording: CircuitRecording, _error: unknown): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+/** Depth of a recording in the call tree: 0 for a top-level circuit, incremented per nested circuit. */
+function depthOf(recording: CircuitRecording | undefined): number {
+  let depth = 0;
+  for (let ancestor = recording?.parent; ancestor; ancestor = ancestor.parent) {
+    depth++;
   }
+  return depth;
 }

package/src/private/circuit_recording/file_circuit_recorder.ts

@@ -3,11 +3,13 @@ import type { Logger } from '@aztec/foundation/log';
 import fs from 'fs/promises';
 import path from 'path';
 
-import type { ACVMWitness } from '../acvm/acvm_types.js';
 import { CircuitRecorder, type CircuitRecording } from './circuit_recorder.js';
 
+/** Per-recording file state, keyed by recording so concurrent/nested executions don't share it. */
+type RecordingFileState = { filePath: string; isFirstCall: boolean };
+
 export class FileCircuitRecorder extends CircuitRecorder {
-  declare recording?: CircuitRecording & { filePath: string; isFirstCall: boolean };
+  readonly #fileState = new WeakMap<CircuitRecording, RecordingFileState>();
 
   constructor(
     private readonly recordDir: string,
@@ -16,16 +18,9 @@ export class FileCircuitRecorder extends CircuitRecorder {
     super(logger);
   }
 
-  override async start(
-    input: ACVMWitness,
-    circuitBytecode: Buffer,
-    circuitName: string,
-    functionName: string = 'main',
-  ) {
-    await super.start(input, circuitBytecode, circuitName, functionName);
-
+  protected override async onStart(recording: CircuitRecording): Promise<void> {
     const recordingStringWithoutClosingBracket = JSON.stringify(
-      { ...this.recording, isFirstCall: undefined, parent: undefined, oracleCalls: undefined, filePath: undefined },
+      { ...recording, parent: undefined, oracleCalls: undefined },
       null,
       2,
     ).slice(0, -2);
@@ -45,13 +40,13 @@ export class FileCircuitRecorder extends CircuitRecorder {
       }
     }
 
-    this.recording!.isFirstCall = true;
-    this.recording!.filePath = await FileCircuitRecorder.#computeFilePathAndStoreInitialRecording(
+    const filePath = await FileCircuitRecorder.#computeFilePathAndStoreInitialRecording(
       this.recordDir,
-      this.recording!.circuitName,
-      this.recording!.functionName,
+      recording.circuitName,
+      recording.functionName,
       recordingStringWithoutClosingBracket,
     );
+    this.#fileState.set(recording, { filePath, isFirstCall: true });
   }
 
   /**
@@ -95,53 +90,48 @@ export class FileCircuitRecorder extends CircuitRecorder {
    * @param inputs - Input arguments
    * @param outputs - Output results
    */
-  override async recordCall(name: string, inputs: unknown[], outputs: unknown, time: number, stackDepth: number) {
-    const entry = await super.recordCall(name, inputs, outputs, time, stackDepth);
-    try {
-      const prefix = this.recording!.isFirstCall ? '    ' : '    ,';
-      this.recording!.isFirstCall = false;
-      await fs.appendFile(this.recording!.filePath, prefix + JSON.stringify(entry) + '\n');
-    } catch (err) {
-      this.logger.error('Failed to log circuit call', { error: err });
+  override async recordCall(name: string, inputs: unknown[], outputs: unknown, time: number) {
+    const entry = await super.recordCall(name, inputs, outputs, time);
+    const recording = this.currentRecording();
+    const state = recording && this.#fileState.get(recording);
+    if (state) {
+      try {
+        const prefix = state.isFirstCall ? '    ' : '    ,';
+        state.isFirstCall = false;
+        await fs.appendFile(state.filePath, prefix + JSON.stringify(entry) + '\n');
+      } catch (err) {
+        this.logger.error('Failed to log circuit call', { error: err });
+      }
     }
     return entry;
   }
 
-  /**
-   * Finalizes the recording file by adding closing brackets. Without calling this method, the recording file is
-   * incomplete and it fails to parse.
-   */
-  override async finish(): Promise<CircuitRecording> {
-    // Finish sets the recording to undefined if we are at the topmost circuit,
-    // so we save the current file path before that
-    const filePath = this.recording!.filePath;
-    const result = await super.finish();
+  /** Closes the recording file with the trailing brackets so the JSON parses. */
+  protected override async onFinish(recording: CircuitRecording): Promise<void> {
+    const state = this.#fileState.get(recording);
+    if (!state) {
+      return;
+    }
     try {
-      await fs.appendFile(filePath, '  ]\n}\n');
+      await fs.appendFile(state.filePath, '  ]\n}\n');
     } catch (err) {
       this.logger.error('Failed to finalize recording file', { error: err });
     }
-    return result!;
   }
 
-  /**
-   * Finalizes the recording file by adding the error and closing brackets. Without calling this method or `finish`,
-   * the recording file is incomplete and it fails to parse.
-   * @param error - The error that occurred during circuit execution
-   */
-  override async finishWithError(error: unknown): Promise<CircuitRecording> {
-    // Finish sets the recording to undefined if we are at the topmost circuit,
-    // so we save the current file path before that
-    const filePath = this.recording!.filePath;
-    const result = await super.finishWithError(error);
+  /** Closes the recording file with the execution error and trailing brackets so the JSON parses. */
+  protected override async onError(recording: CircuitRecording, error: unknown): Promise<void> {
+    const state = this.#fileState.get(recording);
+    if (!state) {
+      return;
+    }
     try {
-      await fs.appendFile(filePath, '  ],\n');
-      await fs.appendFile(filePath, `  "error": ${JSON.stringify(error)}\n`);
-      await fs.appendFile(filePath, '}\n');
+      await fs.appendFile(state.filePath, '  ],\n');
+      await fs.appendFile(state.filePath, `  "error": ${JSON.stringify(error)}\n`);
+      await fs.appendFile(state.filePath, '}\n');
     } catch (err) {
       this.logger.error('Failed to finalize recording file with error', { error: err });
     }
-    return result!;
   }
 }
 

package/src/private/circuit_recording/simulator_recorder_wrapper.ts

@@ -58,24 +58,18 @@ export class SimulatorRecorderWrapper implements CircuitSimulator {
     functionName: string,
     callback: C,
   ): Promise<T> {
-    // Start recording circuit execution
-    await this.recorder.start(input, bytecode, contractName, functionName);
-
-    // If callback was provided, we wrap it in a circuit recorder callback wrapper
+    // If a callback was provided, we wrap it so that its oracle calls are recorded. The wrapped callback reads the
+    // active recording lazily, so it picks up the recording opened by record() below.
     const wrappedCallback = this.recorder.wrapCallback(callback);
-    let result: T;
-    try {
-      result = await simulateFn(wrappedCallback as C);
-    } catch (error) {
-      // If an error occurs, we finalize the recording file with the error
-      await this.recorder.finishWithError(error);
-      throw error;
-    }
 
-    // Witness generation is complete so we finish the circuit recorder
-    const recording = await this.recorder.finish();
+    // record() opens a recording for this circuit, runs the simulation within it, and finalizes it. A simulation
+    // failure is re-thrown unchanged, so recorder bookkeeping never masks the underlying error.
+    const { result, recording } = await this.recorder.record(
+      { input, bytecode, circuitName: contractName, functionName },
+      () => simulateFn(wrappedCallback as C),
+    );
 
-    (result as ACIRExecutionResult).oracles = recording.oracleCalls?.reduce(
+    (result as ACIRExecutionResult).oracles = recording.oracleCalls.reduce(
       (acc, { time, name }) => {
         if (!acc[name]) {
           acc[name] = { times: [] };