[Kart03]

Context

AUTO-1062 / AUTO-60. After each script the sandbox sends back the full local, environment, globals and collectionVariables scopes, and runtime mostly needs only their mutations. With ~4 MB of variables that copy costs ~22 ms and ~22 MB per script. One sandbox thread serves all VUs, so it also caps throughput: in a 44-VU, 20-minute CLI run, a prototype cut the worker peak from 2.65 to 1.92 GB and raised throughput from 32 to 40 rps.

Summary of the change

• New run option script.variableMutationsOnly (default false). When set, event.command.js passes variableMutationsOnly: true to host.execute (needs feat(AUTO-1062): add variableMutationsOnly option to return only scope mutations postman-sandbox#1116). Consumers that don't set it keep today's full-scope round trip. The perf lib opts in.
• When the option is set and a result scope (_variables, environment, globals, collectionVariables) comes back with no values, runtime rebuilds it with applyScopeMutations: a copy of contextToUse[scope] with the mutations applied, and .mutations kept. The script trigger still gets full scopes with mutations, which nested-request and consumers read.
• contextToUse is the masked clone when _forbiddenSecretKeys apply, so masked secrets stay masked in the script result. A sandbox-only prototype failed 9 tests here (8 vault masking, 1 pm.variables).
• Tracked scopes are still updated through result[scope].mutations → applyOn(payload.context[scope]), as before.
• The rebuild copies Variable objects but shares their string values, so it stays cheap even with large values.

Breaking changes

None. The option is off by default, so existing consumers see no change. With it on, an older sandbox ignores it and sends full scopes, which take the old path (detected by values).

Dependencies

postmanlabs/postman-sandbox#1116 (variableMutationsOnly). No gain until runtime bumps postman-sandbox. Until then this PR is behaviour-neutral.

Test plan

Suite	sandbox 6.7.4	sandbox branch
test-unit	571 passing	571 passing
test-integration	1901 passing, 0 failing	1901 passing, 0 failing
test-integration-legacy	not run	33 passing
test-lint	ok	ok

Bench: node copybench.js <runtimeDir> 7 100 (1 request, prerequest + test script, 4.08 MB collection vars, 200 scripts):

	ms/script	host alloc MB/script	sandbox→host MB/script
develop	22.8 / 22.7 / 25.3	22.4 / 22.5 / 22.9	4.55
this + sandbox branch	13.4 / 13.6 / 13.8	14.2 / 14.1 / 14.1	0

Opt-in commit (a2c60f2): new test/integration/sanity/variable-mutations-only.test.js covers default off, opt-in, and the host rebuild when the sandbox sends mutations only (stubbed, so it runs against any sandbox version). Its default-off case fails against the previous hardcoded true. test-integration: 1918 passing, 0 failing. test-unit: 571 passing. The one failure, version.test.js, is down to local node_modules not matching the lockfile, not this change. Lint ok.

Review round (27c2eca): _variables included, rebuild gated on the option, standard integration test plus unit tests over a stubbed host (test/unit/event-command-variable-mutations-only.test.js).

Suite	Result
test-integration, installed sandbox, option off	1919 passing, 0 failing
test-integration, #1116 branch, option forced on	1919 passing, 0 failing
test-integration-legacy, #1116 branch	33 passing
test-unit	576 passing. 1 failing: version.test.js, local node_modules vs lockfile, not this change
lint	ok

Additional notes

Draft to develop. Hold it until the sandbox release, then add the dependency bump.

Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.65%. Comparing base (4e40645) to head (388d0a6).

❌ Your project check has failed because the head coverage (34.08%) is below the target coverage (35.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1568      +/-   ##
===========================================
+ Coverage    77.61%   77.65%   +0.03%     
===========================================
  Files           51       51              
  Lines         4361     4368       +7     
  Branches      1234     1234              
===========================================
+ Hits          3385     3392       +7     
  Misses         732      732              
  Partials       244      244              

Flag	Coverage Δ
integration	68.86% <86.66%> (+<0.01%)	⬆️
legacy	34.08% <46.66%> (-0.08%)	⬇️
unit	47.00% <100.00%> (+0.22%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Kart03]

Full-run results, for reviewers. This was a copy of the PPC Governor collection (AUTO-1062) through a local CLI build: 44 VUs, fixed load, 20 min, 6 GiB / 4 CPU. The run used a prototype that patched the sandbox the same way as this PR (only mutations back for environment, globals and collectionVariables), and the comparison run was identical apart from that.

	Full scopes back	Mutations only
Per script run, ~4 MB of variables (micro-benchmark)	22.5 ms, 22.4 MB allocated	13.3 ms, 14.0 MB allocated
Worker peak	2.65 GB	1.92 GB
Worker avg, minutes 4–12 / after the ACS step	1.20 / 2.23 GB	0.97 / 1.58 GB
Container peak	3.45 GB	2.81 GB
rps after the ACS step	31.7	40.0
Requests outside the time-bound loop	80,828	80,828
Assertions failed / passed	220 / 21,648	220 / 21,648

Why it helps: the allocation profile of the host thread shows the uvm bridge making about 6 copies of the variables per script run (Flatted.stringify + join + postMessage + receive + Flatted.parse), with the sandbox thread mirroring them. One sandbox thread serves all VUs, so the copies also capped throughput. This removes the return trip.

Reviewer guide covering all the AUTO-1062 changes: https://claude.ai/artifact/S7vBMoFxTA9kjzQHhQTXpt

[appurva21]

Why is _variables (local variable scope) not included?

[Kart03]

No blocker, I was keeping the change narrow. It's included now in 27c2eca: _variables is rebuilt from mutations like the other three scopes, before payload.context, state and the partition read it, and the sandbox sends it as mutations too (#1116 now uses CONTEXT_VARIABLE_SCOPES).