build: bump simulator to 0.3.1, mutate private state via updatePrivateState

[0xisk]

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update (if none of the other choices apply)

Fixes #712
Fixes #753
Fixes #754

Simulator bump (#712)

• @openzeppelin/compact-simulator ^0.2.0 → ^0.3.1 (live private-state mutation, compact-tools#131).
• 15 private-state helpers across 9 simulators now go through updatePrivateState — the old read-merge-write left setPrivateState unawaited, so on live they would have proven against stale state.
• The 9 overrideWitness specs in ShieldedAccessControl.test.ts are dry-only (itDryOnly); witnesses bind at deploy on live. All 9 still run on dry.

Integration fixtures (#754)

• sharedInitCollision / composedTokens ported from the pre-0.2.0 sync constructor to static create(); initStateIsolation.spec.ts awaits — all 5 previously-broken tests pass.

CI (#753)

• test.yml now runs test:integration and test:harness (sequentially — they share the compile cache and finish in seconds).

Verified locally: unit 1483 passed / 10 skipped, integration 12 passed, harness 110 passed / 4 skipped, types and lint clean.

PR Checklist

• I have read the Contributing Guide
• I have added tests that prove my fix is effective or that my feature works. See GUIDELINES.md#testing for more information.
• I have added documentation for new methods or changes to existing method behavior. See GUIDELINES.md#documentation for more information.
• CI Workflows Are Passing

Summary by CodeRabbit

• Bug Fixes

  • Improved integration-test coverage for initialization state isolation and invalid access-control witnesses.
  • Tests now correctly handle asynchronous simulator creation and contract interactions.

• Tests

  • Added dedicated integration and harness test steps to automated testing.
  • Updated simulator state handling across access-control and token scenarios for more reliable test behavior.
  • Updated the simulator package used by contract tests.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4ef244bc-06ce-4453-b1c4-f6eb5186c239

📥 Commits

Reviewing files that changed from the base of the PR and between 3e841d2 and 8d22f6c.

⛔ Files ignored due to path filters (1)

• yarn.lock is excluded by !**/yarn.lock, !**/*.lock

📒 Files selected for processing (15)

• .github/workflows/test.yml
• contracts/package.json
• contracts/src/access/test/ShieldedAccessControl.test.ts
• contracts/src/access/test/simulators/AccessControlSimulator.ts
• contracts/src/access/test/simulators/OwnableSimulator.ts
• contracts/src/access/test/simulators/ShieldedAccessControlSimulator.ts
• contracts/src/access/test/simulators/ZOwnablePKSimulator.ts
• contracts/src/token/test/simulators/ConfidentialFungibleTokenSimulator.ts
• contracts/src/token/test/simulators/FungibleTokenSimulator.ts
• contracts/src/token/test/simulators/MultiTokenSimulator.ts
• contracts/src/token/test/simulators/NonFungibleTokenSimulator.ts
• contracts/test/integration/fixtures/composedTokens.ts
• contracts/test/integration/fixtures/confidentialFungibleTokenPublicSupply.ts
• contracts/test/integration/fixtures/sharedInitCollision.ts
• contracts/test/integration/specs/initStateIsolation.spec.ts

---

Walkthrough

The simulator dependency is updated, private-state helpers use updatePrivateState, integration fixtures and assertions adopt asynchronous APIs, live-backend-incompatible access tests are skipped, and CI runs integration and harness suites.

Changes

Simulator and integration test migration

Layer / File(s)	Summary
Private-state update migration contracts/package.json, contracts/src/access/test/simulators/*, contracts/src/token/test/simulators/*, contracts/test/integration/fixtures/confidentialFungibleTokenPublicSupply.ts	Simulator private-state helpers now delegate updates through updatePrivateState, including callback-based cache and identity transitions.
Async integration fixtures contracts/test/integration/fixtures/composedTokens.ts, contracts/test/integration/fixtures/sharedInitCollision.ts, contracts/test/integration/specs/initStateIsolation.spec.ts	Fixtures use asynchronous create factories and circuit methods, while integration tests await calls and assert promise rejections or returned values.
Live-backend access test gating contracts/src/access/test/ShieldedAccessControl.test.ts	Witness-override failure cases use itDryOnly and are skipped against live backends.
CI test expansion .github/workflows/test.yml	The test workflow adds dedicated integration and harness test commands.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• OpenZeppelin/compact-contracts#468: Touches the FungibleToken simulator private-state helpers.
• OpenZeppelin/compact-contracts#562: Updates the same initialization-state integration coverage.
• OpenZeppelin/compact-contracts#620: Relates to simulator private-state migration and backend-aware tests.

Suggested reviewers: andrew-fleming

Poem

A rabbit refactors state with care,
Async carrots now hop everywhere.
Live paths skip the dry-only run,
Integration tests greet the sun.
CI thumps its paws: all done!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly references the two primary changes: bumping the simulator dependency to 0.3.1 and refactoring private-state mutations to use updatePrivateState.
Linked Issues check	✅ Passed	All requirements from linked issues #712, #753, and #754 are fully satisfied: simulator bumped to 0.3.1, private-state helpers updated to use updatePrivateState, overrideWitness tests marked as dry-only, integration fixtures converted to async API, integration and harness tests added to CI, and initStateIsolation tests updated to await simulator creation and circuit calls.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issues: dependency bump, simulator refactoring, test gating, fixture conversion, and CI updates. No unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/bump-simulator-private-state

---

_{Comment @coderabbitai help to get the list of available commands.}