@fluidgrids/workflows 2026.1028.2 → 2026.1030.1

package/README.md

@@ -226,15 +226,66 @@ export const refundOrder = workflow(
   `ctx.signalRun` / `ctx.signalParent` / `ctx.getRunHandle`, `ctx.sideEffect`,
   `ctx.patched` / `ctx.deprecatePatch`, `ctx.now` / `ctx.random` / `ctx.uuid`,
   `ctx.setCurrentDetails`, cancellation scopes, `ctx.saga()`, and the parity
-  commands `ctx.upsertContext` and `ctx.continueAsNew`. User activities, local
-  activities, custom queries, updates and search attributes are Phase C and fail
-  the workflow task with `UNSUPPORTED_COMMAND`.
+  commands `ctx.upsertContext` and `ctx.continueAsNew`. User functions as
+  local activities are not run yet and fail the workflow task with
+  `UNSUPPORTED_COMMAND`.
+- Since C-R1 (Phase C, `RUNTIME_RELEASE = 3`; each feature is enabled by the
+  service per workspace flag, see "Phase C" below): updates
+  (`ctx.handleUpdate(def, fn, { validate })`, `ctx.setDefaultUpdateHandler`),
+  custom queries (`ctx.handleQuery`, `ctx.setDefaultQueryHandler`),
+  `dynamicWorkflow`, user activities (`declareActivity`, `ctx.activity`),
+  `ctx.upsertSearchAttributes`, interceptors (`export const interceptors =
+workflowInterceptors(...)`) with header propagation, and `ctx.sinks`.
+- Since R2 (the runtime release `RUNTIME_RELEASE = 2`):
+  `ctx.localActivity(op, { args, retry, startToCloseTimeout, summary })` runs a
+  short node call inside the workflow task (at most 30 s; the `ctx.run`
+  allow-list applies). The task returns `outcome: 'localActivityRequested'`
+  with the calls it waits for; the worker runs them and runs the same task
+  again with `localActivityResults`, and the task records one
+  `RECORD_LOCAL_ACTIVITY` marker per call. A retryable failure is requested
+  again with the next `attempt` and its `backoffMs`; a replay returns the
+  recorded outcome and never runs the call again. A local activity the first
+  execution dropped (its scope was cancelled in the same activation, or the
+  run completed without awaiting it) records nothing and replays the same way;
+  one that would have been requested but has no marker is a non-determinism.
+- Run handles take a workflow id: `ctx.getRunHandle({ workflowKey, workflowId,
+firstRunId? })`, `ctx.signalRun(target, …)` and `ctx.cancelRun(target)`.
+- `ctx.onSignal(signal, { unfinishedPolicy: 'ABANDON' }, fn)`; a workflow that
+  finishes while a `WARN_AND_ABANDON` handler still runs logs one warning and
+  reports `unfinishedHandlers` in the task result (never on replay).
+- `ctx.info.lastResult`, `lastFailure`, `workflowId`, `runAttempt`, `summary`,
+  `details`, `context` (the memo), the timeouts, `retry`, `priority` and
+  `versioningBehavior` come from `WORKFLOW_STARTED`, so a replay sees what the
+  first execution saw; histories written before R2 fall back to the lease.
+- `workflow(name, { versioningBehavior, retry, runTimeout, executionTimeout,
+workflowTaskTimeout })` lowers to `config`; `lower()` writes the runtime
+  features a bundle uses to `code.features` (`localActivity`, `externalCancel`,
+  `childOptions`, `canOptions`, `autoUpgrade`, `runRetry`, `timeouts`) so the
+  service can refuse a push whose features its flags do not enable. The call
+  sites are read in every module of the project (helpers and vendored packages
+  included), and any use of the name `localActivity` counts. Each function's
+  settings are also written to `code.exports.workflows[fn].config`: the
+  service resolves run options per `workflowFn` from that table, so a
+  same-bundle child that runs on its parent's definition gets its own retry
+  and timeouts.
+- The command feature gate (`commandFeatures`, `isWorkflowCommandEnabled(cmd,
+features)`, `isReliefCommand`, `PHASE_B_CORE_FEATURES`,
+  `PHASE_B_PARITY_FEATURES`) is the one contract the service and the workers use
+  to enable parity commands. Every option the R1 runtime wrote stays in the
+  core set (`CORE_CHILD_OPTIONS`, `CORE_CAN_OPTIONS`), so a Phase B workflow
+  behaves the same with `fluidgrids.durable-parity` off; only the R2 options
+  (child `retry`, `versioningBehavior`, `idReusePolicy`, `idConflictPolicy`,
+  and a run-retry `continueAsNew` `retry`) need the flag. A continue-as-new
+  `retry` in the R1 activity shape (`retryDelay`, `maxRetries`) is still
+  written as R1 wrote it and has no effect; `continueAsNewRetryShape` tells
+  the shapes apart, and the service must ignore the legacy one; `rolloutBucket(key)` (FNV-1a 32 over UTF-8, modulo 100) is the rollout hash.
 - Only store and registry nodes and `internal:http`, `internal:datatable`,
   `internal:set` and `internal:code` may run as activities
   (`ACTIVITY_NODE_ALLOWLIST`).
 - An `ApplicationError` (or any failure class, or a class listed in
   `failureErrorTypes`) fails the run; any other throw, a determinism violation
-  or a Phase C call fails only the workflow task, which the engine retries.
+  or a user local activity fails only the workflow task, which the engine
+  retries.
 - A cancellation scope function receives a `ctx` bound to its scope; use it
   inside the function. The outer `ctx` joins the scope only while the function
   runs synchronously (`ctx.nonCancellable(() => ctx.run(...))` works), never
@@ -284,12 +335,27 @@ await replay(refundOrder, handle.history()); // throws DeterminismViolation on a
 ```
 
 The test environment appends exactly the events the service appends
-(`eventsForCommands`) and retries activities with `computeRetryDelay`. Its
-documented differences from the service: workflow tasks run in this process
-without the determinism shims (pass `taskExecutor` to run them in an isolate), a
-failed workflow task stops the run instead of being retried, activity
-start-to-close and heartbeat timeouts are not timed (a mock may throw a
-`TimeoutFailure`), and graph children are mocks (`mockChild`).
+(`eventsForCommands`) and retries activities with `computeRetryDelay`. Since R2
+it also runs local activities through `mock` (retried inside the task), start
+delays, run and execution timeouts and run-level retry on the fake clock,
+workflow-id policies (`workflowId`, `idReusePolicy`, `idConflictPolicy`) and
+workflow-id targets, schedule-to-start timeouts while a queue is held
+(`holdActivities`), heartbeat details on retry (`info.heartbeat`,
+`info.heartbeatDetails`), and fails `result()` with `UnfinishedHandlersError`
+when a run finishes while a signal handler still runs
+(`failOnUnfinishedHandlers`, default true). Its documented differences from the
+service: workflow tasks run in this process without the determinism shims (pass
+`taskExecutor` to run them in an isolate), a failed workflow task stops the run
+instead of being retried, activity start-to-close and heartbeat timeouts are not
+timed (a mock may throw a `TimeoutFailure`), local-activity retries do not wait
+for their backoff, the workflow-task timeout is recorded but not enforced, and
+graph children are mocks (`mockChild`).
+
+`buildBundle(files, { sourcemap: 'external' })` also returns the bundle's
+source map (`map`) with the same bundle bytes and `buildId`; it travels in the
+source archive (`map`), and `createSourceMapper`, `mapStackTrace` and
+`mapEnhancedStackTrace` turn the bundle positions of `__stack_trace` and
+`__enhanced_stack_trace` into source lines.
 
 `simulate(definition, { trigger, mocks, workflows })` walks a tier-1 graph in
 process. It is a reduced form: no expressions are evaluated, a node without a
@@ -301,7 +367,11 @@ merges are not modelled.
 
 `fixtures/histories/` holds the recorded histories of spec 10 §3 (timers,
 signals, cancellation, child runs, race, gather, continue-as-new, patched,
-side effects, activities, task failures, activation boundaries, and updates as
+side effects, activities, task failures, activation boundaries, the 21 R2
+parity histories (local activities, schedule-to-start, heartbeat details,
+cancellation types, child options, run retry, continue-as-new results and
+options, run and execution timeouts, start delay, external cancels, handler
+drain, auto-upgrade, task failures and failure types), and updates as
 parse-only fixtures), with their workflow sources in `fixtures/histories/src/`
 and the scenarios that recorded them in `fixtures/histories/scenarios.ts`.
 `bun run check:histories` re-records every history, replays it in QuickJS and in
@@ -310,6 +380,106 @@ completed workflow task to exactly the commands it recorded, then does all of
 it again under `TZ=Asia/Kolkata`; `tests/histories.test.ts` adds the in-process
 replay. `--write` re-records.
 
+### Phase C (C-R1)
+
+Every Phase C capability is written into the bundle's `code.features`
+(`userActivity`, `updates`, `queries`, `searchAttributes`, `dynamic`,
+`interceptors`) and into the command gate (`c.userActivity`, `c.updates`,
+`c.searchAttributes`), so the service refuses it until the workspace's flag is
+on (`CODE_FEATURE_FLAGS`, `PHASE_C_FEATURE_FLAGS`): `fluidgrids.run-control`
+for updates, queries, dynamic workflows and interceptors,
+`fluidgrids.search-attributes` for search attributes and
+`fluidgrids.self-hosted-workers` for user activities. A bundle built before
+C-R1 reports no runtime `capabilities` and the service does not deliver it
+updates or custom queries.
+
+```ts
+import { declareActivity, defineQuery, defineUpdate, workflow } from '@fluidgrids/workflows';
+
+const charge = declareActivity<{ amount: number }, { id: string }>('billing.charge', {
+  taskQueue: 'payments',
+});
+const setAddress = defineUpdate<{ address: string }, { ok: boolean }>('setAddress');
+const status = defineQuery<{ address: string }>('status');
+
+export const order = workflow(
+  'order',
+  { updates: [setAddress], queries: [status] },
+  async (ctx) => {
+    let address = '';
+    ctx.handleQuery(status, () => ({ address }));
+    ctx.handleUpdate(
+      setAddress,
+      (args) => {
+        address = args.address;
+        return { ok: true };
+      },
+      {
+        validate: (args) => {
+          if (!args.address) throw new Error('empty');
+        },
+      }
+    );
+    ctx.upsertSearchAttributes({ stage: 'charging' });
+    return ctx.activity(charge, { args: { amount: 10 }, startToCloseTimeout: '30s' });
+  }
+);
+```
+
+- Updates (05 §6, 11 §2.39): the lease delivers pending updates to a workflow
+  task (`request.updates`); the validator runs read-only and a rejection
+  writes nothing to history (`REJECT_UPDATE`); acceptance appends
+  `UPDATE_ACCEPTED` with the request and the handler's result or failure
+  `UPDATE_COMPLETED`. A replay re-delivers accepted updates after the
+  activation's inputs without their validators; `UPDATE_ADMITTED`
+  (update-with-start, reset) is delivered as an input and validated. An update
+  no handler takes by the end of its activation is rejected with
+  `UpdateNotHandled`.
+- Queries run after the replay, read-only: a command, a sink call or a
+  side effect in a query handler (or an update validator) throws
+  `QueryHandlerSideEffect`. A name without a handler is answered with
+  `rejected: true`. Queries may also ride on a workflow task
+  (`request.queries`, CX8).
+- `dynamicWorkflow(name, (ctx, workflowFn, input) => ...)` serves every
+  function name the bundle does not export (`code.exports.workflows["*"]`).
+- `ctx.activity(declaration | name, options)` issues `SCHEDULE_ACTIVITY` of kind
+  `user` on the option's task queue, else the declaration's, else the run's;
+  `managed` refuses user activities. `implementActivity`, `defineActivity`
+  and `dynamicActivity` are for the worker: `lower()` reports
+  `durable.activityImplInBundle` when a workflow module pulls one into the
+  bundle. `ActivityPausedError` is what an activity throws after a heartbeat
+  reports `paused`.
+- Query handlers and update validators are read-only: commands, sinks,
+  `ctx.random()`, `ctx.uuid()`, `Math.random()`, new patches and
+  `setCurrentDetails` throw `QueryHandlerSideEffect`, because validators do
+  not run again on replay.
+- Interceptors (11 §2.10): a bundle's `interceptors` export runs only in a
+  task whose request lists `interceptors` in `features` (the workspace has
+  `fluidgrids.run-control` on); otherwise the task fails with
+  `UNSUPPORTED_COMMAND`. Inbound `execute`, `handleSignal`, `handleQuery`,
+  `validateUpdate`, `handleUpdate`; outbound `scheduleActivity`,
+  `scheduleLocalActivity`, `startTimer`, `startChild`, `signalRun`,
+  `cancelRun`, `sideEffect`, `continueAsNew`, `upsertSearchAttributes`,
+  `upsertContext`, `getLogAttributes`. Headers travel on starts, signals,
+  updates, activities, children and continue-as-new.
+- `ctx.sinks.<sink>.<fn>(...args)` calls are returned once in the task result
+  (`sinkCalls`, at most 256), never on replay; managed runs ignore them.
+- Contracts: `schema/bridge-v2.schema.json` (worker bridge protocol 2,
+  `validateBridgeFrame`) and `schema/payload-fields.json` (`PAYLOAD_FIELDS`,
+  the encoded payload form `{"$fgp":1, encoding, metadata, data}` and
+  `isEncodedPayload`). Failures nest through `cause`, so they are listed
+  apart (`FAILURE_FIELDS`, `COMMAND_FAILURE_FIELDS`): the payload of a failure
+  is its `details` at every level of the cause chain. Codecs call
+  `mapEventPayloads(type, payload, fn)` and `mapCommandPayloads(command, fn)`,
+  which apply both lists. The IR gains `internal:signal-run`,
+  `internal:set-search-attributes` and the schedule policy and spec fields
+  (`checkSchedulePolicy`; `startAt`, `endAt`, `excludeCalendars` in
+  `checkScheduleSpec`).
+- Test environment: `update`, `startWithUpdate`, `query`, `reset`,
+  `registerActivity` / `mockActivity` with `completeActivityAsync`, search
+  attributes and headers at the start, `interceptors`,
+  `activityInterceptors` and `sinks`.
+
 ## Shared fixtures
 
 `fixtures/` holds the conformance fixtures shared with the Python SDK: every

package/dist/{activation-BBh1p82z.d.cts → activation-DqUfpHzk.d.cts}

@@ -1,4 +1,4 @@
-import { U as RunEventRecord } from './types-CpBBjaGX.cjs';
+import { R as RunEventRecord } from './types-Bv2i4cBX.cjs';
 
 /**
  * Split a history into activations (C-HIST, spec 04 §2).

package/dist/{activation-DnhG7SmF.d.ts → activation-xpx1oWuo.d.ts}

@@ -1,4 +1,4 @@
-import { U as RunEventRecord } from './types-DV-HX_Gt.js';
+import { R as RunEventRecord } from './types-DGx-b9eq.js';
 
 /**
  * Split a history into activations (C-HIST, spec 04 §2).