@fluidgrids/workflows 2026.1029.1 → 2026.1030.1

package/README.md

@@ -226,9 +226,16 @@ 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, user
-  functions as 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`
@@ -277,7 +284,8 @@ features)`, `isReliefCommand`, `PHASE_B_CORE_FEATURES`,
   (`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
@@ -372,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-CESehfYi.d.cts → activation-DqUfpHzk.d.cts}

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

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

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