Skip to content

0.4.0: close the gaps between definition and the legacy authoring surface - #6

Merged
bweis merged 1 commit into
mainfrom
feat/0.4.0-close-definition-gaps
Sep 11, 2026
Merged

bweis merged 1 commit into
mainfrom
feat/0.4.0-close-definition-gaps

Conversation

@bweis

@bweis bweis commented Sep 11, 2026

Copy link
Copy Markdown
Contributor

What

0.4.0 makes the definition + bundle + activities + client/engine-client + testing surface complete enough that an application never imports the legacy modules, then deprecates those modules for deletion in 0.5.0.

Every gap here is something the Springbird monorepo still had to reach into engine-sandbox, typed-activity, versioning, or mailbox for:

  1. Timers on the seamsleep, sleepUntil from definition (shared timestamp rule sleepUntilTarget). In memory they follow Effect's Clock, so TestClock.adjust drives them and the grace-period race (mailbox take vs timer) is pinned in both orders on both engines.
  2. continueAsNew on the seam — in memory it interrupts the fiber and records the continuation (world.continuedAsNewOf(W)), payload round-tripped through the workflow schema.
  3. Child workflows on the seamexecuteChild(Child, payload, { discard? }); Temporal dispatches into upstream execute (identical commands). makeTestWorkflowOps({ workflows: [handleWorkflow(Child, handler)] }) runs children in-process, forks discarded ones, attaches on a taken id.
  4. Type helpersPayloadOf/SuccessOf/ErrorOf/AnyTypedActivity/… on definition; codecsFor/ACTIVITY_EXIT_TYPE on wire.
  5. Client-side driving — every engine-client / WorkflowClient op accepts the declaration directly (or its primitive); new completeDeferred. Fake client: offer/offersTo; harness client: offer/request/stateOf/resolve.
  6. versioned(site, { v1, v2 }) — run-table form of version; the main-fiber lint rule recognises it.
  7. UpdateRequest — one parameter order (definition's <P, S, E>); the engine-sandbox alias is deprecated.
  8. bundle moduleworkflowBundle's home, "the one file the worker points at"; the rest of engine-sandbox is documented engine-level or deprecated.
  9. effect pin4.0.0-rc.112.

Deprecations carry @deprecated + replacement; the new prefer-definition lint rule (error in recommended) reports every deprecated import with its replacement. CHANGELOG.md has the 0.5.0 deletion checklist under "Unreleased / planned".

Wire safety

A real defOrder history recorded with the 0.3.0 bundle before any code changed lives in fixtures/histories/; replay-compat.test.ts replays it through this bundle. OrderFlow's handler is byte-for-byte unchanged; the 0.4.0 fixtures sit beside it.

Validation

  • typecheck, oxlint, build, docs build (dead links): clean
  • full suite: 25 files / 72 tests green, unloaded run (one load-induced batch timeout while two example servers ran concurrently; passes alone and on rerun)
  • both examples typecheck and run end to end on the new surface
  • consumer checks over examples/: no engine-sandbox import besides workflowBundle, no typed-activity/versioning/mailbox; oxlint with recommended exits 0 there and fails on the deprecated fixtures

…face

Timers (sleep, sleepUntil), continueAsNew, and child workflows
(executeChild) join the WorkflowOps seam; versioned() is the run-table
form of version(); the activity type helpers move to definition and
codecsFor/ACTIVITY_EXIT_TYPE to wire; every client-side op accepts the
declaration directly, plus completeDeferred; the new bundle module is the
one sandbox import an application has.

makeTestWorkflowOps implements all of it in memory: TestClock-driven
timers (not instant), recorded continue-as-new, in-process children via
handleWorkflow bindings with attach-on-taken-id. The fake client gains
offer/offersTo; the live harness gains offer/request/stateOf/resolve.

Deprecated (removed in 0.5.0): engine-sandbox's per-primitive calls,
sleepUntil, continueAsNew, UpdateRequest alias; TypedActivity.make; the
mailbox/update/state-cell make constructors; Versioning.match/version.
New prefer-definition lint rule (recommended preset, error) reports each
with its replacement.

A history recorded on 0.3.0 replays through this bundle
(replay-compat.test.ts). effect pinned to 4.0.0-rc.112.
@bweis
bweis added this pull request to the merge queue Sep 11, 2026
Merged via the queue into main with commit f480844 Sep 11, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant