Golem Scala SDK Development
Work from sdks/scala/ unless a command says repository root. The Scala SDK is independent of the root Rust build: cargo make build does not build it.
Authoritative build matrix
- JDK 21+, sbt 1.12.x (
project/build.propertiesis authoritative) - Scala 3.8.2 for SDK modules and the Mill plugin build
- Scala 2.12.21 only for sbt 1.x plugin loading and its shared codegen dependency
- Scala 3.3.7 in the current Mill consumer fixtures; this is fixture configuration, not a general Scala.js limit
- Mill 1.1.8 and Scala.js 1.22.0 in the current Mill build
Scala 2 applications are not supported. project/plugins.sbt, build.sbt, and mill/build.mill are the version sources of truth. Always select the intended Scala version explicitly, especially with an sbt client that may retain session state.
Current project IDs
Use sbt project IDs, not artifact names:
modelJVM,modelJS,core,macros,codegensbtPlugin,testAgents,integrationTests- fixtures:
emptyAutoRegisterFixture,middlewareGuestLinkFixture
The published sbt plugin is loaded with addSbtPlugin("dev.zio" % "zio-golem-sbt" % version) and enabled as golem.sbt.GolemPlugin. The Mill plugin is loaded as dev.zio::zio-golem-mill and mixed in via golem.mill.GolemAutoRegister. Check the example and Mill README for complete consumer setup.
Compile and test
Start with affected projects, then compile testAgents for public API, macro, codegen, or plugin changes:
sbt "++3.8.2; core/compile"
sbt "++3.8.2; modelJVM/test; modelJS/test"
sbt "++3.8.2; macros/test; codegen/test"
sbt "++2.12.21!; codegen/test; sbtPlugin/test"
sbt "++3.8.2; testAgents/fastLinkJS"
sbt golemTestAll covers Scala 3 model/core/macros tests and links testAgents; it deliberately excludes codegen, Scala 2.12, sbt-plugin, and integration tests. Add those checks explicitly when affected. Use scoped scalafmtCheckAll; run scalafmtAll only to fix formatting.
Local publication
The canonical SDK alias is:
cd sdks/scala
sbt golemPublishLocal
For the repository's complete local prerequisite flow (WIT sync, the guest runtime, all cross-published modules, and marker caching), use:
# Repository root
cargo make build-sdk-scala
Delete sdks/scala/target/.local-publish-marker before rerunning that cargo-make task when inputs changed. For release/CI-sensitive work, copy the explicit publish matrix from current Makefile.toml or .github/workflows/ci.yaml; do not preserve an older hand-written sequence in documentation.
Runtime and WIT changes
The Scala.js core exposes the current schema-based host surface. Useful authorities are:
HostApi.scalafor typed agent IDs, registry/metadata, oplog, update/fork/revert, promises, and relatedgolem:api/host@1.5.0facades;host/DurabilityApi.scalafor schema-typed synchronous and asynchronous custom durable calls;runtime/rpc/andRpcCodegen.scalafor invocation and mode-aware client signatures;wit/main.witfor the Preview 3 guest world and current versioned dependencies.
DurabilityApi.durable and durableAsync support sequential and properly nested custom operations
only. An async body may await host calls when no unrelated guest work runs during the wait. Do not
overlap it with other futures or callbacks, including ordinary host calls: sibling effects can
acquire the wrong scope and cause incorrect replay or invocation failure. Misuse is not reliably
detected. Await each nested operation; do not detach work. All outstanding work must terminate
before the body exits, including on failure; a failed Future does not cancel its siblings.
Durable generated clients return plain values/Unit plus cancellation tokens where applicable. Ephemeral invocations return metadata-bearing InvocationResult, InvocationReceipt, CancelableAsyncInvocation, and CancelableInvocationReceipt values. Do not describe the old wasm-rpc resource API without checking these files.
After WIT or guest-role changes, sync and regenerate as described by golem-scala-base-image. The script uses wasm-rquickjs 0.4.15 with TypeScript transformation, Preview 3, and wasm32-wasip2; generated WASMs are ignored while ordinary-role d.ts files are tracked.
Example and end-to-end work
example/ is a standalone consumer. Its README, build.sbt, golem.yaml, and run.sh are authoritative. Publish locally before building it. Use the repository binary name golem, not the retired golem-cli, and do not assume the example reproduces every test-agent or multi-component scenario.
For platform behavior use the dedicated integration-test skill. Do not run heavyweight Scala or integration builds merely to verify documentation edits.