fix(simulator): clear the #145 review comments (#147)

* fix(simulator): pin simulated block time to zero

compact-runtime 0.18 defaults `createCircuitContext`'s `time` to
wall-clock, where the hand-rolled 0.16 `QueryContext` left it at 0. Any
suite reading `kernel.blockTime()` silently became non-reproducible.

Threads an explicit `time` from `BaseSimulatorOptions` through to the
runtime factory, defaulting to 0 to restore the previous behaviour.

* refactor(simulator): drop the dead circuit-context helpers

`useCircuitContext` and `useCircuitContextSender` had no callers and were
never exported from the barrel, so they were unreachable before this
migration and got hand-ported to the 0.18 call-tree shape untested.

* fix(simulator): guard context reads before init()

0.18 split construction from state building, so a caller that skipped
`init()` got `Cannot read properties of undefined (reading
'callContext')`. Both `CircuitContextManager.context` and the simulator's
`contractAddress` now throw a named error instead.

* fix(simulator): declare initialState async on IMinimalContract

The canonical interface still promised the sync-only 0.16 return type, so
anything typed against it got the wrong shape and
`CircuitContextManager` carried a private redeclaration to compensate.

* fix(simulator): typecheck the test tree

`tsconfig.types.json` compiled `src/**` only, and its `exclude` named a
`tests` directory that does not exist, so nothing verified the test tree.
Adding a project that covers it surfaced 74 errors, of which the
load-bearing one is in `src/`: 0.18 circuits return
`Promise<CircuitResults>`, which the `ContextlessCircuits` /
`AsyncCircuits` conditionals did not match, collapsing every entry on
`circuits.pure` and `circuits.impure` to `never`.

* src: match the promised circuit shape; keep the anonymous class's
  address field underscore-public for declaration emit
* test: give relative imports the `.js` extension nodenext requires
* wiring: run both projects under `yarn types`, and let turbo see the
  test tree so a regression is not cached away

* fix(simulator): build the setContext fixture as a real 0.18 context

The replacement context was a hand-rolled literal in the pre-0.18 flat
shape, so `setContext`'s only test asserted against a context the runtime
would reject. `toEqual` compared two plain objects and passed anyway.

Rebuilds it through `createCircuitContext` and asserts identity plus the
two fields the test is about. Exporting `BackendDeps` is required for the
same reason: it appears in `create`/`_create`, so an exported binding
assigned from `createSimulator(...)` could not name it (TS4023).

* fix(ci): make the prerelease compiler input functional and verified

* `COMPACTC_VERSION` is now exported to `$GITHUB_ENV`. `VER` was
  step-scoped, so `test/setup.ts` never saw it: overriding the input
  installed one toolchain while the fixtures compiled with the hardcoded
  default.
* The archive is checked against a pinned SHA-256 before it is unpacked
  and executed. The release publishes no checksum file, so the digests
  are pinned per platform here; overriding the version requires passing
  its digest.

* fix(simulator): key the fixture cache on the compiler

The staleness check compared artifact mtime against source mtime only,
so an existing clone kept its 0.31-compiled artifacts and hit a load-time
rejection against the 0.18 runtime. CI never saw it: the `test` turbo
task is uncached and the checkout is clean.

Artifacts now carry a stamp of the compiler version and the zkir flag,
and recompile when it does not match. The flag also moves onto the
fixture list, replacing a `secp256k1` regex over the source that a
mention in a comment was enough to trip.

* test(simulator): collapse the field-to-bytes helpers

Two near-identical copies existed in the test tree. The one in
`SampleZOwnable.test.ts` silently truncated where the runtime helper it
replaced threw, so a wrong value would read as a passing assertion.

Keeps one in the shared test utils, with the range check restored, and
derives `zeroUint8Array` from it. `Signers.ts` keeps its own copy: `src`
cannot import from `test`.

* test(simulator): consume the generated secp256k1 types

The `Ecdsa.compact` re-export is live: the artifact's `index.d.ts`
declares both `Secp256k1EcdsaSignature` and `Secp256k1Point`. The
simulator hand-rolled the signature struct and took the point from the
runtime instead, so a change to the generated shape would not surface
here.

* docs(simulator): correct the sync-era comments

The async migration left the docs describing a synchronous engine: the
dry primitive called "synchronous", `DryBackend` said it wraps a
synchronous result in a resolved promise and preserves dry behaviour
"byte-for-byte", and the `SyncSimulator` name now describes nothing.

Renaming the exported type is a breaking change, so it keeps the name
with a `@remarks` note. Also records that `copyCircuitContext` is
`@internal` upstream.

* ci(turbo): declare COMPACTC_VERSION on the test task

The setup action exports it and `test/setup.ts` reads it, but the task
never declared it. Pass-through happens to work on turbo 2.9, so this
only pins the behaviour against a stricter env mode.

* fix(ci): compile fixtures before the type check

`yarn types` now covers `test/**`, which imports the generated artifacts,
but `checks.yml` runs it before `yarn test` — the only thing that
compiled them. It passed locally only because the artifacts were already
on disk.

Lifts fixture compilation into its own turbo task that `types` depends
on. `test/setup.ts` gains a direct entry point so the task does not have
to go through vitest; vitest's `globalSetup` still calls the same
function.

Author: 0xisk

.github/actions/setup/action.yml

@@ -10,6 +10,10 @@ inputs:
     description: "Pre-release Compact compiler to fetch from GitHub releases (bridge until the toolchain ships stable). Keep in sync with setup.ts COMPACTC_VERSION."
     required: false
     default: "0.33.0-rc.2"
+  compact-prerelease-sha256:
+    description: "SHA-256 of the pre-release compiler archive. Required when overriding compact-prerelease; the default version's digests are built in."
+    required: false
+    default: ""
 
 runs:
   using: "composite"
@@ -58,17 +62,51 @@ runs:
       shell: bash
       env:
         VER: ${{ inputs.compact-prerelease }}
+        SHA_OVERRIDE: ${{ inputs.compact-prerelease-sha256 }}
       run: |
         set -euo pipefail
         # Reuse the platform dir the CLI already created for the stable install
         # (e.g. x86_64-unknown-linux-musl), so the pre-release lands where the
         # `+<version>` selector resolves it; fall back to the host triple.
         PLAT="$(basename "$(find "$HOME/.compact/versions" -mindepth 2 -maxdepth 2 -type d 2>/dev/null | head -1)" 2>/dev/null || true)"
         [ -z "$PLAT" ] && PLAT="$(uname -m)-unknown-linux-musl"
+
+        # The release publishes no checksum file, so the expected digests are
+        # pinned here (computed from the published assets). Overriding the
+        # version means supplying its digest too — this archive is unpacked and
+        # executed, and every other action in this file is pinned by SHA.
+        if [ -n "$SHA_OVERRIDE" ]; then
+          WANT="$SHA_OVERRIDE"
+        else
+          case "$VER/$PLAT" in
+            0.33.0-rc.2/x86_64-unknown-linux-musl)
+              WANT=3055ab92bbc8d5bb0d6282b661b83761d2a0de2ee37e21cf7107e25aaf2a9aad ;;
+            0.33.0-rc.2/aarch64-unknown-linux-musl)
+              WANT=3aa23812b0b086dbce07da3931a40dcb01bec9676b1ceed7f2d0be370ab2dc46 ;;
+            0.33.0-rc.2/x86_64-darwin)
+              WANT=dce1a57d82ce06208fcc5d9de5343f18c48654a5ff3acf6bafabe3d17bf1ef18 ;;
+            0.33.0-rc.2/aarch64-darwin)
+              WANT=35a28009c9a57d20902e4fcfd12f0ca9ea94338208954cf8bcd335652e24f382 ;;
+            *)
+              echo "::error::no pinned digest for $VER/$PLAT; pass compact-prerelease-sha256"
+              exit 1 ;;
+          esac
+        fi
+
         DEST="$HOME/.compact/versions/$VER/$PLAT"
         mkdir -p "$DEST"
         curl -fsSL -o /tmp/compactc.zip \
           "https://github.com/LFDT-Minokawa/compact/releases/download/compactc-v$VER/compactc_v${VER}_${PLAT}.zip"
+        # sha256sum on Linux runners, shasum on macOS.
+        if command -v sha256sum >/dev/null; then
+          echo "$WANT  /tmp/compactc.zip" | sha256sum -c -
+        else
+          echo "$WANT  /tmp/compactc.zip" | shasum -a 256 -c -
+        fi
         unzip -oq /tmp/compactc.zip -d "$DEST"
         chmod +x "$DEST"/*
         compact compile +"$VER" --version
+
+        # `test/setup.ts` reads COMPACTC_VERSION to pick the toolchain it
+        # compiles fixtures with; without this the input has no effect there.
+        echo "COMPACTC_VERSION=$VER" >> "$GITHUB_ENV"

packages/simulator/package.json

@@ -35,7 +35,8 @@
   },
   "scripts": {
     "build": "tsc -p .",
-    "types": "tsc -p tsconfig.types.json",
+    "compile:fixtures": "node test/setup.ts",
+    "types": "tsc -p tsconfig.types.json && tsc -p tsconfig.test.json",
     "test": "MIDNIGHT_BACKEND=dry vitest run",
     "test:live": "MIDNIGHT_BACKEND=live vitest run",
     "clean": "git clean -fXd"

packages/simulator/src/backend/Backend.ts

@@ -26,7 +26,7 @@ export type CircuitKind = 'pure' | 'impure';
  * `createBackendSimulator` builds the async circuit proxies, caller helpers, and
  * state getters on top of this interface; the backend itself stays dumb. Every
  * operation is async so spec code is uniform `await` across both backends:
- * {@link DryBackend} wraps its synchronous results in `Promise.resolve`,
+ * {@link DryBackend} resolves in memory,
  * the live adapter awaits the network.
  *
  * @template P - Private state type.
@@ -77,7 +77,7 @@ export interface Backend<P, L> {
    * implements `setPrivateState`; otherwise it throws
    * `PRIVATE_STATE_MUTATION_UNSUPPORTED` (from the live backend).
    *
-   * Async across backends for uniform `await`: dry resolves synchronously,
+   * Async across backends for uniform `await`: dry resolves in memory,
    * live awaits the provider write.
    *
    * @param privateState - The new private state `P`.

packages/simulator/src/backend/DryBackend.ts

@@ -6,10 +6,14 @@ import type { Signers } from '../signers/Signers.js';
 import type { Backend, BackendKind, CircuitKind } from './Backend.js';
 
 /**
- * The slice of a synchronous `createSimulator` instance that {@link DryBackend}
+ * The slice of a local `createSimulator` instance that {@link DryBackend}
  * drives. Kept structural so the dry backend reuses the existing simulator
  * machinery without coupling to its concrete (anonymous) class.
  *
+ * @remarks Named `SyncSimulator` for the pre-0.18 runtime, whose circuits
+ * returned their result directly. They return promises now; renaming the type
+ * is a breaking change left for a later release.
+ *
  * @template P - Private state type.
  * @template L - Public ledger state type.
  */
@@ -30,14 +34,13 @@ export interface SyncSimulator<P, L> {
 }
 
 /**
- * The in-memory backend: a thin async facade over the existing synchronous
- * `createSimulator` instance.
+ * The in-memory backend: a thin facade over the local `createSimulator`
+ * instance.
  *
- * Every operation delegates to the wrapped simulator and wraps the synchronous
- * result in a resolved promise, so a circuit never returns a bare value
- * on dry but a `Promise` on live. Because all real work routes through the
- * unchanged synchronous path, dry behavior is preserved byte-for-byte
- * and is the parity reference the live backend is measured against.
+ * Every operation delegates to the wrapped simulator and resolves to a promise,
+ * so a circuit never returns a bare value on dry but a `Promise` on live. All
+ * real work routes through the in-memory path, which is the parity reference the
+ * live backend is measured against.
  *
  * @template P - Private state type.
  * @template L - Public ledger state type.
@@ -49,7 +52,7 @@ export class DryBackend<P, L> implements Backend<P, L> {
   private readonly signers: Signers;
 
   /**
-   * @param sim - The wrapped synchronous simulator instance.
+   * @param sim - The wrapped in-memory simulator instance.
    * @param signers - Resolver used to turn caller aliases into deterministic keys.
    */
   constructor(sim: SyncSimulator<P, L>, signers: Signers) {

packages/simulator/src/core/CircuitContextManager.ts

@@ -3,29 +3,31 @@ import {
   type CoinPublicKey,
   type ConstructorContext,
   type ContractAddress,
-  type ContractState,
   createCircuitContext,
   createConstructorContext,
-  type EncodedZswapLocalState,
 } from '@midnight-ntwrk/compact-runtime';
+import type { InitialStateResult } from '../types/Contract.js';
 
 /**
  * A composable utility class for managing Compact contract state in simulations.
  *
  * Handles initialization and lifecycle management of the `CircuitContext`,
  * which includes private state, public (ledger) state, zswap local state, and transaction context.
  */
-/** Shape of a compiled contract's constructor result (sync or async in 0.18). */
-type InitialStateResult<P> = {
-  currentPrivateState: P;
-  currentContractState: ContractState;
-  currentZswapLocalState: EncodedZswapLocalState;
-};
-
 export class CircuitContextManager<P> {
-  // Assigned by the async `init()`; the manager is always constructed and then
-  // awaited (`init`) before any circuit call reads the context.
-  public context!: CircuitContext<P>;
+  private _context?: CircuitContext<P>;
+
+  /** The built context. Throws if read before {@link init} has been awaited. */
+  get context(): CircuitContext<P> {
+    if (!this._context) {
+      throw new Error('CircuitContextManager: call init() before use');
+    }
+    return this._context;
+  }
+
+  set context(newContext: CircuitContext<P>) {
+    this._context = newContext;
+  }
 
   private readonly contract: {
     initialState: (
@@ -36,6 +38,7 @@ export class CircuitContextManager<P> {
   private readonly privateState: P;
   private readonly coinPK: CoinPublicKey;
   private readonly contractAddress: ContractAddress;
+  private readonly time: number;
   private readonly contractArgs: any[];
 
   /**
@@ -50,6 +53,8 @@ export class CircuitContextManager<P> {
    * @param privateState - The initial private state to inject into the contract
    * @param coinPK - The caller's coin public key
    * @param contractAddress - Optional override for the contract's address
+   * @param time - Block time in seconds since the epoch, as the kernel's time
+   *   operations observe it
    * @param contractArgs - Additional arguments to pass to the contract constructor
    */
   constructor(
@@ -62,12 +67,14 @@ export class CircuitContextManager<P> {
     privateState: P,
     coinPK: CoinPublicKey,
     contractAddress: ContractAddress,
+    time: number,
     ...contractArgs: any[]
   ) {
     this.contract = contract;
     this.privateState = privateState;
     this.coinPK = coinPK;
     this.contractAddress = contractAddress;
+    this.time = time;
     this.contractArgs = contractArgs;
   }
 
@@ -94,6 +101,10 @@ export class CircuitContextManager<P> {
       currentZswapLocalState,
       currentContractState.data,
       currentPrivateState,
+      undefined, // stateProvider: no cross-contract calls in the simulator
+      undefined, // gasLimit: runtime default
+      undefined, // costModel: runtime default
+      this.time,
     );
   }
 

packages/simulator/src/core/ContractSimulator.ts

@@ -51,6 +51,9 @@ export abstract class ContractSimulator<P, L> extends AbstractSimulator<P, L> {
     // compact-runtime 0.18: the caller-scoped fields live on `callContext`.
     // Copy (shallow-clones `callContext`) before overriding the Zswap local
     // state so the base context is left untouched.
+    // `copyCircuitContext` is `@internal` upstream, so a patch release could
+    // drop it; hand-rolling the copy is the worse option.
+    // TODO: drop this note once the runtime makes it public.
     const ctx = copyCircuitContext(baseCtx) as CircuitContext<P>;
     ctx.callContext.currentZswapLocalState = emptyZswapLocalState(activeCaller);
     return ctx;

packages/simulator/src/create-contract.type-test.ts

@@ -1,19 +1,12 @@
 /**
  * Type-level regression guard for the static `create` / `_create` contract.
  *
- * `yarn types` compiles `src/**` but NOT `test/**` (the sample simulators import
- * generated, gitignored contract artifacts), and `vitest` strips types without
- * checking them — so a regression in the `create` / `_create` typing would
- * otherwise pass CI. This file reproduces the subclass-override pattern against a
- * synthetic contract type, so `yarn types` fails on a regression.
+ * Reproduces the subclass-override pattern against a synthetic contract type, so
+ * the guard holds without a compiled artifact. Carries the negative assertions
+ * (`@ts-expect-error`) that the real simulators cannot express.
  *
- * It exports nothing and is imported by nothing (inert at runtime). The build
- * config (`tsconfig.json`) excludes `*.type-test.ts` from emit, so it never
- * reaches `dist`; the type check runs it via `tsconfig.types.json`.
- *
- * Typechecking the real test simulators (which need the generated artifacts) is a
- * separate, larger effort; this is the minimal guard for the contract that
- * actually regressed.
+ * Exports nothing and is imported by nothing. The build config excludes
+ * `*.type-test.ts` from emit so it never reaches `dist`; `yarn types` compiles it.
  */
 import { createSimulator } from './factory/createSimulator.js';
 import type { SimulatorConfig } from './factory/SimulatorConfig.js';

packages/simulator/src/factory/createDrySimulator.ts

@@ -12,11 +12,11 @@ import type { BaseSimulatorOptions } from '../types/Options.js';
 import type { SimulatorConfig } from './SimulatorConfig.js';
 
 /**
- * Internal synchronous simulator primitive.
+ * Internal in-memory simulator primitive.
  *
- * This is the in-memory engine the public async {@link createSimulator} builds on:
- * the dry backend wraps an instance of this class, and the live backend uses one
- * locally to evaluate pure circuits. It is not the public testing API —
+ * This is the engine the public {@link createSimulator} builds on: the dry
+ * backend wraps an instance of this class, and the live backend uses one locally
+ * to evaluate pure circuits. It is not the public testing API —
  * use {@link createSimulator} instead.
  *
  * Creates a class extending ContractSimulator with witness management, state
@@ -34,11 +34,22 @@ export function createDrySimulator<
 >(config: SimulatorConfig<P, L, W, TContract, TArgs>) {
   return class GeneratedSimulator extends ContractSimulator<P, L> {
     contract: TContract;
-    // Assigned by the async `init()` (0.18 made `initialState` async, so the
-    // address — read from the built context — is not known at construction).
-    contractAddress!: string;
+    // Underscore-public, not private: declaration emit rejects private members
+    // on this exported anonymous class (TS4094). Treat as internal.
+    public _contractAddress?: string;
     public _witnesses: W;
 
+    /**
+     * The contract's address, read from the built context. Throws if read
+     * before {@link init} has been awaited.
+     */
+    get contractAddress(): string {
+      if (!this._contractAddress) {
+        throw new Error('Simulator: await init() before use');
+      }
+      return this._contractAddress;
+    }
+
     /**
      * Creates a new simulator instance with explicit contract args and options
      */
@@ -53,6 +64,9 @@ export function createDrySimulator<
         witnesses = config.witnessesFactory(),
         coinPK = '0'.repeat(64),
         contractAddress = dummyContractAddress(),
+        // Fixed rather than wall-clock, so a run that reads `kernel.blockTime()`
+        // is reproducible. Override via `options.time`.
+        time = 0,
       } = options;
 
       this._witnesses = witnesses;
@@ -65,6 +79,7 @@ export function createDrySimulator<
         privateState,
         coinPK,
         contractAddress,
+        time,
         ...processedArgs,
       );
     }
@@ -76,7 +91,7 @@ export function createDrySimulator<
      */
     async init(): Promise<this> {
       await this.circuitContextManager.init();
-      this.contractAddress =
+      this._contractAddress =
         this.circuitContext.callContext.currentQueryContext.address;
       return this;
     }

packages/simulator/src/factory/createSimulator.ts

@@ -14,8 +14,13 @@ import type { SimulatorOptions } from '../types/Options.js';
 import { createDrySimulator } from './createDrySimulator.js';
 import type { SimulatorConfig } from './SimulatorConfig.js';
 
-/** Prepared backend wiring handed to the simulator constructor. */
-interface BackendDeps<P, L> {
+/**
+ * Prepared backend wiring handed to the simulator constructor.
+ *
+ * Exported because it appears in `create` / `_create`, so a consumer that
+ * assigns `createSimulator(...)` to an exported binding must be able to name it.
+ */
+export interface BackendDeps<P, L> {
   backend: Backend<P, L>;
   signers: Signers;
   pureNames: string[];
@@ -54,7 +59,7 @@ export function createSimulator<
   TContract extends IMinimalContract,
   TArgs extends readonly any[] = readonly any[],
 >(config: SimulatorConfig<P, L, W, TContract, TArgs>) {
-  // Built once per factory; instances per `create()`. The synchronous primitive
+  // Built once per factory; instances per `create()`. The in-memory primitive
   // is the whole dry path and the local JS artifact for pure-circuit eval.
   const DrySimClass = createDrySimulator<P, L, W, TContract, TArgs>(config);
 
@@ -81,7 +86,7 @@ export function createSimulator<
   ): Promise<BackendDeps<P, L>> => {
     const kind = resolveBackendKind(options.backend);
 
-    // The local synchronous simulator: the whole dry path, and the pure-circuit
+    // The local in-memory simulator: the whole dry path, and the pure-circuit
     // evaluator in live (D2). In live this runs `initialState` in memory only —
     // it is never deployed on-chain.
     const localSim = new DrySimClass(contractArgs, options);

packages/simulator/src/index.ts

@@ -14,6 +14,7 @@ export { PrivateStateMutator } from './core/PrivateStateMutator.js';
 // `createSimulator`. `createLiveContext`/`registerLiveBackend` are
 // values, but their static graph is midnight-js-free (type-only + dynamic
 // import), so exporting them from the main barrel keeps the wall up.
+export type { BackendDeps } from './factory/createSimulator.js';
 export { createSimulator } from './factory/createSimulator.js';
 export type { SimulatorConfig } from './factory/SimulatorConfig.js';
 export type {
@@ -65,6 +66,7 @@ export type {
   ExtractPureCircuits,
   IContractSimulator,
   IMinimalContract,
+  InitialStateResult,
 } from './types/index.js';
 export type {
   BaseSimulatorOptions,