That did it. I had to restructure a bit to get the correct flow for cycling through multiple file records, but it worked as you described.
A few follow-up questions —
1. why do we have to use the field key instead of the field name? I see no meaningful distinction between them, except that the field key is more cumbersome to work with.
2. why didn’t the add_row() (or update_row()) function work? based on the documentation, I should have been able to achieve what I needed using that function (which seems simpler and more straightforward than your solution).