@lostgradient/weft 0.3.0 → 0.4.0

package/dist/core/types/workflow-log.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The `ctx.log` structured-logging surface: the {@link WorkflowLogger} exposed on
+ * the workflow context, the {@link WorkflowLogRecord} envelope it emits, and the
+ * {@link WorkflowLogLevel} severity. Split out from `workflow-context.ts` so the
+ * context module stays under the line cap and the log types can be re-exported as
+ * a cohesive cluster.
+ *
+ * @module core/types/workflow-log
+ */
+/**
+ * Severity of a {@link WorkflowLogRecord}, ordered `debug < info < warn < error`.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowLogLevel } from '@lostgradient/weft';
+ * const isError = (level: WorkflowLogLevel) => level === 'error';
+ * ```
+ */
+export type WorkflowLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * The structured record a {@link WorkflowLogger} emits for one log call. Envelope
+ * fields (`level`, `message`, `workflowId`, `workflowType`, `timestamp`) are
+ * engine-owned and always present; caller `attributes` nest under their own key so
+ * they can never shadow an envelope field. `timestamp` is wall-clock ms at emit —
+ * observability metadata, never checkpointed or replayed. Type a host sink
+ * installed via `EngineOptions.onLog` with this record.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type WorkflowLogRecord } from '@lostgradient/weft';
+ * const engine = new Engine({ onLog: (r: WorkflowLogRecord) => console.log(r.level, r.message) });
+ * ```
+ */
+export interface WorkflowLogRecord {
+    readonly level: WorkflowLogLevel;
+    readonly message: string;
+    readonly workflowId: string;
+    readonly workflowType: string;
+    readonly timestamp: number;
+    readonly attributes?: Record<string, unknown>;
+}
+/**
+ * The structured logger exposed as `WorkflowContext.log`. Each method emits
+ * a {@link WorkflowLogRecord} to the current process console (`console.debug` /
+ * `console.info` / `console.warn` / `console.error`) with `workflowId`,
+ * `workflowType`, `level`, and `timestamp` auto-attached. Caller-supplied
+ * `attributes` are nested under their own key and cannot overwrite the envelope.
+ *
+ * Replay behavior: a workflow body re-executes from the start on recovery to
+ * rebuild state. Log calls in the already-committed replay window are suppressed,
+ * so a recovered run does not re-emit logs it already emitted. Suppression is
+ * per-position: a log call sitting at a step the engine has already cached is
+ * silenced; a log call at the live frontier emits. This holds in both inline and
+ * worker execution modes.
+ *
+ * Two replay caveats. A log placed *after* the last committed step re-fires on
+ * recovery, because there is no cached step to suppress it (the same caveat
+ * Temporal's workflow logger carries); likewise a workflow with no committed
+ * durable step has no replay position to suppress against, so its logs may
+ * re-emit on recovery. Logs inside `ctx.all` / `ctx.runAll` branches follow that
+ * branch's re-execution semantics.
+ *
+ * A host sink installed via `EngineOptions.onLog` receives records from BOTH execution
+ * modes: inline records directly, and worker-mode records forwarded from the worker
+ * back to the host. When no sink is installed, worker-mode records go to the worker
+ * process console (and inline records to the engine-host console). Inline log
+ * timestamps come from the engine clock; worker-mode timestamps come from the worker
+ * process wall clock.
+ *
+ * Exported so a host can also type a logger it injects through `ctx.services`
+ * (the pre-`ctx.log` pattern).
+ *
+ * @example
+ * ```ts
+ * import { workflow, type WorkflowContext, type WorkflowLogger } from '@lostgradient/weft';
+ *
+ * const myWorkflow = workflow({ name: 'my-workflow' }).execute(async function* (
+ *   ctx: WorkflowContext,
+ * ) {
+ *   ctx.log?.info('workflow started', { attempt: 1 });
+ *   ctx.log?.warn('retrying activity', { reason: 'timeout' });
+ *   // A host logger injected through `ctx.services` can reuse this type:
+ *   const { log } = (ctx.services ?? {}) as { log?: WorkflowLogger };
+ *   log?.error('activity failed', { error: 'ECONNREFUSED' });
+ * });
+ * void myWorkflow;
+ * ```
+ */
+export interface WorkflowLogger {
+    /** Emit a `debug` record. Auto-carries `workflowId`/`workflowType`; suppressed during replay. */
+    debug(message: string, attributes?: Record<string, unknown>): void;
+    /** Emit an `info` record. Auto-carries `workflowId`/`workflowType`; suppressed during replay. */
+    info(message: string, attributes?: Record<string, unknown>): void;
+    /** Emit a `warn` record. Auto-carries `workflowId`/`workflowType`; suppressed during replay. */
+    warn(message: string, attributes?: Record<string, unknown>): void;
+    /** Emit an `error` record. Auto-carries `workflowId`/`workflowType`; suppressed during replay. */
+    error(message: string, attributes?: Record<string, unknown>): void;
+}

package/dist/core/types/workflow-registries.d.ts

@@ -32,6 +32,7 @@ export interface WorkflowRegistry {
 export type WorkflowRegistryEntry = {
     input: unknown;
     output: unknown;
+    services?: unknown;
 };
 declare const defaultWorkflowRegistry: unique symbol;
 declare const defaultActivityTypes: unique symbol;
@@ -73,7 +74,7 @@ export type IsDefaultWorkflowRegistry<TRegistry extends object> = TRegistry exte
  */
 export type AnyWorkflowDefinition = {
     readonly name: string;
-    readonly handler: WorkflowFunction<never> | StepWorkflowFunction<never>;
+    readonly handler: WorkflowFunction<never, unknown, never> | StepWorkflowFunction<never>;
 };
 /**
  * Broad activity-definition constraint used by {@link Engine.create} and
@@ -100,6 +101,14 @@ export type WorkflowInput<TRegistry extends object, TName extends string> = TNam
 export type WorkflowOutput<TRegistry extends object, TName extends string> = TName extends keyof TRegistry ? TRegistry[TName] extends {
     output: infer TOutput;
 } ? TOutput : unknown : unknown;
+export type WorkflowServices<TRegistry extends object, TName extends string> = TName extends keyof TRegistry ? TRegistry[TName] extends {
+    services: infer TServices;
+} ? TServices : unknown : unknown;
+export type WorkflowServicesUnion<TRegistry extends object> = [keyof TRegistry & string] extends [
+    never
+] ? unknown : {
+    [Name in keyof TRegistry & string]: WorkflowServices<TRegistry, Name>;
+}[keyof TRegistry & string];
 export type ActivityArguments<TActivities extends object, TName extends string> = TName extends keyof TActivities ? TActivities[TName] extends () => unknown ? [] : TActivities[TName] extends (input: infer TInput) => unknown ? [input: TInput] : [input: unknown] : [input?: unknown];
 export type ActivityResult<TActivities extends object, TName extends string> = TName extends keyof TActivities ? TActivities[TName] extends (...arguments_: infer _TArguments) => infer TResult ? Awaited<TResult> : unknown : unknown;
 export type RegisteredActivityFunction<TActivities extends object, TName extends string> = TName extends keyof TActivities ? TActivities[TName] extends () => infer TResult ? () => TResult : TActivities[TName] extends (input: infer TInput) => infer TResult ? (input: TInput) => TResult : never : never;
@@ -122,16 +131,18 @@ type MergeDefinitionEntries<TUnion> = [TUnion] extends [never] ? {} : UnionToInt
  * void input;
  * ```
  */
-export type InferWorkflowEntry<TDefinition extends AnyWorkflowDefinition> = TDefinition extends WorkflowDefinition<infer TInput, infer TOutput, infer TName extends string> ? {
+export type InferWorkflowEntry<TDefinition extends AnyWorkflowDefinition> = TDefinition extends WorkflowDefinition<infer TInput, infer TOutput, infer TName extends string, infer TServices> ? {
     [Name in TName]: {
         input: TInput;
         output: TOutput;
+        services: TServices;
     };
 } : never;
-type InferWorkflowEntryForKey<TName extends string, TDefinition extends AnyWorkflowDefinition> = TDefinition extends WorkflowDefinition<infer TInput, infer TOutput> ? {
+type InferWorkflowEntryForKey<TName extends string, TDefinition extends AnyWorkflowDefinition> = TDefinition extends WorkflowDefinition<infer TInput, infer TOutput, string, infer TServices> ? {
     [Name in TName]: {
         input: TInput;
         output: TOutput;
+        services: TServices;
     };
 } : never;
 /**

package/dist/core/types/workflow-registry.d.ts

@@ -1,5 +1,6 @@
 import type { DefinitionSchema } from './definition-schema.ts';
 import type { SearchAttributeSchema } from './search-attributes.ts';
+import type { WorkflowConcurrencyOptions } from './workflow-concurrency.ts';
 /**
  * Read-only metadata exposed by the engine for a registered workflow type.
  *
@@ -28,4 +29,6 @@ export interface RegisteredWorkflowDefinition<TInput = unknown, TOutput = unknow
     outputSchema?: DefinitionSchema<unknown, TOutput>;
     /** Optional search attribute schema used for indexing and runtime validation. */
     searchAttributes?: SearchAttributeSchema;
+    /** Optional start admission policy for this workflow type. */
+    concurrency?: WorkflowConcurrencyOptions<TInput>;
 }

package/dist/core/types.d.ts

@@ -1,3 +1,4 @@
+export * from './types/activity-verification.ts';
 export * from './types/activity.ts';
 export * from './types/archive-adapter.ts';
 export * from './types/bulk.ts';
@@ -8,6 +9,7 @@ export * from './types/definition-schema.ts';
 export * from './types/history-policy.ts';
 export * from './types/identity.ts';
 export * from './types/launch-metadata.ts';
+export * from './types/list-options.ts';
 export * from './types/message-handles.ts';
 export * from './types/options.ts';
 export * from './types/payload-size-policy.ts';
@@ -22,8 +24,10 @@ export * from './types/state.ts';
 export * from './types/workflow-builder-helpers.ts';
 export * from './types/workflow-builder-runtime.ts';
 export * from './types/workflow-builder.ts';
+export * from './types/workflow-concurrency.ts';
 export * from './types/workflow-context.ts';
 export * from './types/workflow-function.ts';
+export * from './types/workflow-log.ts';
 export * from './types/workflow-registries.ts';
 export * from './types/workflow-registry.ts';
 export * from './types/workflow-snapshot.ts';

package/dist/core/types.js

@@ -1,3 +1,4 @@
+export * from "./types/activity-verification.js";
 export * from "./types/activity.js";
 export * from "./types/archive-adapter.js";
 export * from "./types/bulk.js";
@@ -8,6 +9,7 @@ export * from "./types/definition-schema.js";
 export * from "./types/history-policy.js";
 export * from "./types/identity.js";
 export * from "./types/launch-metadata.js";
+export * from "./types/list-options.js";
 export * from "./types/message-handles.js";
 export * from "./types/options.js";
 export * from "./types/payload-size-policy.js";
@@ -22,8 +24,10 @@ export * from "./types/state.js";
 export * from "./types/workflow-builder-helpers.js";
 export * from "./types/workflow-builder-runtime.js";
 export * from "./types/workflow-builder.js";
+export * from "./types/workflow-concurrency.js";
 export * from "./types/workflow-context.js";
 export * from "./types/workflow-function.js";
+export * from "./types/workflow-log.js";
 export * from "./types/workflow-registries.js";
 export * from "./types/workflow-registry.js";
 export * from "./types/workflow-snapshot.js";

package/dist/core/versioning.d.ts

@@ -1,62 +1,32 @@
 /**
- * Workflow version comparison and checkpoint migration.
+ * Workflow version comparison and checkpoint diagnostics.
  *
  * Provides utilities for detecting version mismatches between stored
- * and registered workflow definitions, running checkpoint migrations,
- * and building atomic batch operations for version updates.
+ * and registered workflow definitions.
  *
  * @module versioning
  */
-import type { BatchOperation } from '../storage/interface.ts';
 import { WeftError } from './weft-error.ts';
 import type { WorkflowVersionDiff } from './workflow-version-tuple.ts';
 /** Default version string assigned when no version is specified. */
 export declare const DEFAULT_WORKFLOW_VERSION = "0.0.0";
-export type VersionCompatibility = 'compatible' | 'needs-migration' | 'incompatible';
+export type VersionCompatibility = 'compatible' | 'incompatible';
 /**
  * Compare a stored workflow version with the currently registered version.
  *
  * - `"compatible"` — versions match; no action needed.
- * - `"needs-migration"` — versions differ and a migration function is available.
- * - `"incompatible"` — versions differ and no migration is available; the engine
- *   will throw a {@link VersionMismatchError} instead of resuming silently.
+ * - `"incompatible"` — versions differ; the engine will throw a
+ *   {@link VersionMismatchError} instead of resuming silently.
  *
  * @example
  * ```ts
  * import { checkVersionCompatibility } from '@lostgradient/weft';
  *
- * console.log(checkVersionCompatibility('1.0.0', '1.0.0', false)); // 'compatible'
- * console.log(checkVersionCompatibility('1.0.0', '2.0.0', true));  // 'needs-migration'
- * console.log(checkVersionCompatibility('1.0.0', '2.0.0', false)); // 'incompatible'
+ * console.log(checkVersionCompatibility('1.0.0', '1.0.0')); // 'compatible'
+ * console.log(checkVersionCompatibility('1.0.0', '2.0.0')); // 'incompatible'
  * ```
  */
-export declare function checkVersionCompatibility(storedVersion: string, registeredVersion: string, hasMigration: boolean): VersionCompatibility;
-/**
- * Run a migration function on checkpoint data, transforming it from one
- * version to another.
- *
- * The caller is responsible for serializing the result back to bytes if needed.
- *
- * @example
- * ```ts
- * import { migrateCheckpoint } from '@lostgradient/weft';
- *
- * const oldData = { step: 0, locals: { counter: 1 }, version: '1.0.0' };
- * const migrated = migrateCheckpoint(oldData, '1.0.0', '2.0.0', (data) => {
- *   const d = data as typeof oldData;
- *   return { ...d, locals: { ...d.locals, newField: 'default' } };
- * });
- * void migrated;
- * ```
- */
-export declare function migrateCheckpoint(checkpointData: unknown, fromVersion: string, _toVersion: string, migrate: (checkpoint: unknown, fromVersion: string) => unknown): unknown;
-/**
- * Build batch operations that atomically update the checkpoint and workflow
- * state after a successful migration.
- *
- * The returned operations are suitable for passing to `Storage.batch()`.
- */
-export declare function buildVersionUpdateOperations(workflowId: string, newCheckpointBytes: Uint8Array, _newVersion: string, workflowStateBytes: Uint8Array): BatchOperation[];
+export declare function checkVersionCompatibility(storedVersion: string, registeredVersion: string): VersionCompatibility;
 /** Description of a single field-level difference between checkpoint shapes. */
 export type FieldDiff = {
     field: string;
@@ -115,7 +85,7 @@ export type ShapeDiffOptions = {
 };
 /**
  * Thrown when a workflow's stored version does not match its registered
- * version and no migration path is available or the migration failed.
+ * version.
  *
  * When shape information is provided, the error message includes a
  * field-level diff describing exactly which fields changed.

package/dist/core/versioning.js

@@ -1,20 +1,10 @@
-import { KEYS } from "../storage/interface.js";
 import { WeftError } from "./weft-error.js";
 import { formatWorkflowVersionDiff } from "./workflow-version-tuple.js";
 export const DEFAULT_WORKFLOW_VERSION = "0.0.0";
-export function checkVersionCompatibility(storedVersion, registeredVersion, hasMigration) {
+export function checkVersionCompatibility(storedVersion, registeredVersion) {
   if (storedVersion === registeredVersion)
     return "compatible";
-  return hasMigration ? "needs-migration" : "incompatible";
-}
-export function migrateCheckpoint(checkpointData, fromVersion, _toVersion, migrate) {
-  return migrate(checkpointData, fromVersion);
-}
-export function buildVersionUpdateOperations(workflowId, newCheckpointBytes, _newVersion, workflowStateBytes) {
-  return [
-    { type: "put", key: KEYS.checkpoint(workflowId), value: newCheckpointBytes },
-    { type: "put", key: KEYS.workflow(workflowId), value: workflowStateBytes }
-  ];
+  return "incompatible";
 }
 export function diffCheckpointShapes(oldShape, newShape) {
   const diffs = [], allKeys = new Set([...Object.keys(oldShape), ...Object.keys(newShape)]);

package/dist/core/weft-error.d.ts

@@ -9,6 +9,9 @@
  * when an error may have crossed a realm or duplicate-module boundary, where
  * `instanceof` is unreliable.
  *
+ * See `documentation/reference/api-errors.md` for the source-complete error
+ * code table and usage guidance for the exported guards.
+ *
  * @example
  * ```ts
  * import { isWeftErrorLike, type WeftErrorCode } from '@lostgradient/weft';
@@ -22,7 +25,7 @@
  * }
  * ```
  */
-export type WeftErrorCode = 'WorkflowAlreadyExistsError' | 'BulkDeleteRequiresTerminalWorkflowsError' | 'BulkOperationConfirmationError' | 'WorkflowTypeNotRegisteredForRecoveryError' | 'EngineCreateNameMismatchError' | 'EngineDisposedError' | 'WorkflowNotFoundError' | 'WorkflowNotRegisteredError' | 'ActivityResolutionError' | 'PersistedDataIncompatibleError' | 'WorkflowTimeoutError' | 'HttpClientError' | 'WorkerProtocolIncompatibleError' | 'UpdateTimeoutError' | 'UpdateValidationError' | 'WorkflowTerminalError' | 'WorkflowBuilderError' | 'VersionMismatchError' | 'EffectReplayConflictError' | 'ReviewTimeoutError' | 'AtomicStateConflictError' | 'StandardSchemaValidationError' | 'ActivityReconciliationCapabilityError' | 'ActivityReconciliationConflictError' | 'ActivityReconciliationIndeterminateError' | 'AsyncActivityTokenNotFoundError' | 'PayloadSizeExceededError' | 'StartOrSignalConflictError' | 'IdempotencyKeyPurgedError';
+export type WeftErrorCode = 'WorkflowAlreadyExistsError' | 'BulkDeleteRequiresTerminalWorkflowsError' | 'BulkOperationConfirmationError' | 'WorkflowTypeNotRegisteredForRecoveryError' | 'EngineCreateNameMismatchError' | 'EngineDisposedError' | 'WorkflowNotFoundError' | 'WorkflowNotRegisteredError' | 'WorkflowConcurrencyLimitExceededError' | 'WorkflowSuspendNotSupportedError' | 'ActivityResolutionError' | 'BranchTopologyChangedError' | 'PersistedDataIncompatibleError' | 'WorkflowTimeoutError' | 'HttpClientError' | 'WorkerProtocolIncompatibleError' | 'UpdateTimeoutError' | 'UpdateValidationError' | 'WorkflowTerminalError' | 'WorkflowBuilderError' | 'VersionMismatchError' | 'EffectReplayConflictError' | 'ReviewTimeoutError' | 'AtomicStateConflictError' | 'StandardSchemaValidationError' | 'ActivityReconciliationCapabilityError' | 'ActivityReconciliationConflictError' | 'ActivityReconciliationIndeterminateError' | 'AsyncActivityTokenNotFoundError' | 'ActivityScheduleToCloseTimeoutError' | 'ActivityPerAttemptTimeoutError' | 'PayloadSizeExceededError' | 'StartOrSignalConflictError' | 'IdempotencyKeyPurgedError';
 /**
  * Generic abstract base for all Weft library errors. The `TCode` parameter
  * makes each subclass's `code` its own literal type; the exported base surface
@@ -55,6 +58,9 @@ export declare abstract class WeftError<TCode extends string = string> extends E
  * object structurally. {@link isWeftErrorCode} narrows a bare `code` *string*,
  * not a caught `unknown`.
  *
+ * See `documentation/reference/api-errors.md#error-helpers` for guard selection
+ * examples across same-realm and cross-boundary errors.
+ *
  * @example
  * ```ts
  * import { isWeftError } from '@lostgradient/weft';
@@ -71,6 +77,9 @@ export declare function isWeftError(value: unknown): value is WeftError;
  * a caught `unknown` (the common `catch` case), reach for {@link isWeftErrorLike},
  * which checks the whole error object structurally.
  *
+ * See `documentation/reference/api-errors.md#error-helpers` for guard selection
+ * examples across same-realm and cross-boundary errors.
+ *
  * @example
  * ```ts
  * import { isWeftErrorCode } from '@lostgradient/weft';
@@ -96,6 +105,9 @@ export declare function isWeftErrorCode(value: unknown): value is WeftErrorCode;
  * To match a *specific* code, narrow with this guard then compare `error.code`
  * — TypeScript narrows it to the matched literal in the branch.
  *
+ * See `documentation/reference/api-errors.md#error-helpers` for guard selection
+ * examples across same-realm and cross-boundary errors.
+ *
  * @example
  * ```ts
  * import { isWeftErrorLike } from '@lostgradient/weft';
@@ -112,3 +124,34 @@ export declare function isWeftErrorLike(value: unknown): value is {
     code: WeftErrorCode;
     message: string;
 };
+/**
+ * Transport-uniform error classification: `true` when `error` represents the
+ * given public {@link WeftErrorCode}, whether it was thrown in process or
+ * arrived over HTTP. This is the canonical way to branch on a specific Weft
+ * error without caring which transport produced it — the predicate the
+ * `WeftClient` "constructor change, not an API change" promise rests on.
+ *
+ * It matches two shapes with one rule:
+ * - An in-process typed error (or any {@link isWeftErrorLike} value) whose
+ *   `code` equals `code` — what `LocalClient` throws.
+ * - An `HttpClientError` carrying `weftCode === code` — what `HttpClient`
+ *   throws when the REST fault rehydrated the originating public code. The
+ *   check is structural (`'weftCode' in error`) rather than `instanceof
+ *   HttpClientError`, both to stay reliable across realm/duplicate-module
+ *   boundaries and to keep this guard in the core layer without importing the
+ *   client.
+ *
+ * @example
+ * ```ts
+ * import { isWeftFault } from '@lostgradient/weft';
+ *
+ * // The same branch holds over LocalClient and HttpClient: a missing workflow
+ * // is a no-op success ("nothing to tell"), not a failure to re-raise.
+ * function rethrowUnlessMissing(error: unknown): void {
+ *   if (!isWeftFault(error, 'WorkflowNotFoundError')) {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export declare function isWeftFault(error: unknown, code: WeftErrorCode): boolean;

package/dist/core/weft-error.js

@@ -15,7 +15,10 @@ const publicWeftErrorCodeMap = {
   EngineDisposedError: !0,
   WorkflowNotFoundError: !0,
   WorkflowNotRegisteredError: !0,
+  WorkflowConcurrencyLimitExceededError: !0,
+  WorkflowSuspendNotSupportedError: !0,
   ActivityResolutionError: !0,
+  BranchTopologyChangedError: !0,
   PersistedDataIncompatibleError: !0,
   WorkflowTimeoutError: !0,
   HttpClientError: !0,
@@ -33,6 +36,8 @@ const publicWeftErrorCodeMap = {
   ActivityReconciliationConflictError: !0,
   ActivityReconciliationIndeterminateError: !0,
   AsyncActivityTokenNotFoundError: !0,
+  ActivityScheduleToCloseTimeoutError: !0,
+  ActivityPerAttemptTimeoutError: !0,
   PayloadSizeExceededError: !0,
   StartOrSignalConflictError: !0,
   IdempotencyKeyPurgedError: !0
@@ -52,3 +57,14 @@ export function isWeftErrorLike(value) {
     return !1;
   }
 }
+export function isWeftFault(error, code) {
+  if (isWeftErrorLike(error) && error.code === code)
+    return !0;
+  if (typeof error !== "object" || error === null)
+    return !1;
+  try {
+    return "weftCode" in error && error.weftCode === code;
+  } catch {
+    return !1;
+  }
+}

package/dist/core/worker-execution-strategy-options.d.ts

@@ -1,7 +1,33 @@
+import type { WorkflowLogRecord } from './types/workflow-log.ts';
 export interface WorkerExecutionStrategyOptions {
     broadcastEvents?: boolean;
     workflowTurnTimeoutMs?: number;
     maxProtocolMessageBytes?: number;
     requireProtocolVersion?: boolean;
     discardOnCancel?: boolean;
+    /**
+     * The engine host's `EngineOptions.onLog` sink (#529). When present, the strategy
+     * tells each worker (`hostHasLogSink: true` on `run`/`resume`) to forward `ctx.log`
+     * records back as `log` protocol messages, which are delivered here instead of the
+     * worker console. When absent, workers log to their own console (the default).
+     */
+    onLog?: (record: WorkflowLogRecord) => void;
+    /**
+     * Monotonic-enough wall clock (ms) for the forwarded-log abuse counter's flood
+     * window (#545). Injected so tests advance time deterministically; defaults to
+     * `Date.now` when omitted (the non-worker-construction path / direct tests).
+     */
+    getNow?: () => number;
+    /**
+     * Internal test seams for the forwarded-log abuse counter (#545). Not a public
+     * engine option — the abuse thresholds are deliberately fixed and generous so honest
+     * high-log workflows are never discarded. These exist only so unit tests can inject
+     * small thresholds (and a controllable window) to exercise the discard paths without
+     * sending thousands of messages; each falls back to its worker-protocol default.
+     */
+    forwardedLogFloodWindowMs?: number;
+    /** See {@link WorkerExecutionStrategyOptions.forwardedLogFloodWindowMs} — internal test seam (#545). */
+    forwardedLogFloodThreshold?: number;
+    /** See {@link WorkerExecutionStrategyOptions.forwardedLogFloodWindowMs} — internal test seam (#545). */
+    forwardedLogStrikeThreshold?: number;
 }

package/dist/core/worker-execution-strategy.js

@@ -1,14 +1,20 @@
 import { WorkerCheckpointResumeState } from "./worker-checkpoint-resume-state.js";
-import {
-  WorkerExecutionDispatcher
-} from "./worker-execution-dispatcher.js";
+import { WorkerExecutionDispatcher } from "./worker-execution-dispatcher.js";
 import { WorkerExecutionOwnership } from "./worker-execution-ownership.js";
+import {
+  buildResumeMessage,
+  buildRunMessage
+} from "./worker-inbound-message.js";
 import { WorkerListenerRegistry } from "./worker-listener-registry.js";
+import {
+  forwardedLogGateFromStrategyOptions
+} from "./worker-log-abuse-counter.js";
 import {
   emitWorkerMessageToEngine,
   isParkableWaitSignalCheckpoint
 } from "./worker-message-helpers.js";
 import { WorkerProtocolGuard } from "./worker-protocol-guard.js";
+import { isWorkerLogMessage } from "./worker-protocol-log.js";
 import { WORKER_PROTOCOL_VERSION } from "./worker-protocol.js";
 import { WorkerTurnWatchdog } from "./worker-turn-watchdog.js";
 
@@ -23,6 +29,7 @@ export class WorkerExecutionStrategy {
   #maxProtocolMessageBytes;
   #requireProtocolVersion;
   #discardOnCancel;
+  #forwardedLogGate;
   #turnWatchdog;
   #protocolGuard;
   #dispatcher;
@@ -30,14 +37,22 @@ export class WorkerExecutionStrategy {
   #disposed;
   #nextTurnId;
   constructor(pool, options) {
+    const {
+      workflowTurnTimeoutMs,
+      maxProtocolMessageBytes,
+      requireProtocolVersion = !1,
+      discardOnCancel = !1,
+      broadcastEvents = !1
+    } = options ?? {};
     this.#pool = pool;
     this.#ownership = new WorkerExecutionOwnership;
     this.#workerListeners = new WorkerListenerRegistry;
     this.#checkpointResumeState = new WorkerCheckpointResumeState;
-    this.#workflowTurnTimeoutMs = options?.workflowTurnTimeoutMs;
-    this.#maxProtocolMessageBytes = options?.maxProtocolMessageBytes;
-    this.#requireProtocolVersion = options?.requireProtocolVersion ?? !1;
-    this.#discardOnCancel = options?.discardOnCancel ?? !1;
+    this.#workflowTurnTimeoutMs = workflowTurnTimeoutMs;
+    this.#maxProtocolMessageBytes = maxProtocolMessageBytes;
+    this.#requireProtocolVersion = requireProtocolVersion;
+    this.#discardOnCancel = discardOnCancel;
+    this.#forwardedLogGate = forwardedLogGateFromStrategyOptions(options, maxProtocolMessageBytes);
     this.#turnWatchdog = new WorkerTurnWatchdog(this.#workflowTurnTimeoutMs, (turn) => {
       this.#handleTurnTimeout(turn);
     });
@@ -72,7 +87,7 @@ export class WorkerExecutionStrategy {
     this.#broadcastListener = null;
     this.#disposed = !1;
     this.#nextTurnId = 1;
-    if (options?.broadcastEvents)
+    if (broadcastEvents)
       try {
         this.#broadcastChannel = new BroadcastChannel("weft:events");
         this.#broadcastListener = (event) => {
@@ -87,22 +102,7 @@ export class WorkerExecutionStrategy {
   startWorkflow(parameters) {
     this.#ownership.resetWorkflow(parameters.workflowId);
     this.#checkpointResumeState.resetWorkflow(parameters.workflowId);
-    const message = {
-      type: "run",
-      protocolVersion: WORKER_PROTOCOL_VERSION,
-      turnId: this.#nextTurnId++,
-      workflowId: parameters.workflowId,
-      workflowType: parameters.workflowType,
-      checkpoint: parameters.checkpoint,
-      input: parameters.input,
-      executionStateOwnerId: parameters.executionStateOwnerId ?? parameters.workflowId
-    };
-    if (this.#maxProtocolMessageBytes !== void 0)
-      message.maxProtocolMessageBytes = this.#maxProtocolMessageBytes;
-    if (parameters.deadline !== void 0)
-      message.deadline = parameters.deadline;
-    if (parameters.headers)
-      message.headers = parameters.headers;
+    const message = buildRunMessage(parameters, this.#inboundMessageContext());
     if (!this.#assertHostToWorkerMessageWithinLimit(parameters.workflowId, message))
       return;
     this.#dispatcher.acquireAndSend(parameters.workflowId, message);
@@ -111,12 +111,14 @@ export class WorkerExecutionStrategy {
     const worker = this.#ownership.getActiveWorker(parameters.workflowId);
     if (worker) {
       this.#checkpointResumeState.recordResume(parameters.workflowId);
-      this.#dispatcher.postResumeMessage(worker, parameters, this.#createResumeMessage(parameters));
+      const resumeMessage = buildResumeMessage(parameters, this.#inboundMessageContext());
+      this.#dispatcher.postResumeMessage(worker, parameters, resumeMessage);
       return;
     }
     const parkedWorker = this.#ownership.getParkedWorker(parameters.workflowId);
     if (parkedWorker) {
-      this.#dispatcher.resumeParkedWorkflow(parameters, parkedWorker, this.#createResumeMessage(parameters));
+      const resumeMessage = buildResumeMessage(parameters, this.#inboundMessageContext());
+      this.#dispatcher.resumeParkedWorkflow(parameters, parkedWorker, resumeMessage);
       return;
     }
     if (this.#ownership.consumeCancelled(parameters.workflowId))
@@ -128,18 +130,12 @@ export class WorkerExecutionStrategy {
         error: `No worker assigned for workflow: ${parameters.workflowId}`
       });
   }
-  #createResumeMessage(parameters) {
-    const message = {
-      type: "resume",
-      protocolVersion: WORKER_PROTOCOL_VERSION,
+  #inboundMessageContext() {
+    return {
       turnId: this.#nextTurnId++,
-      workflowId: parameters.workflowId,
-      checkpoint: parameters.checkpoint,
-      operationResult: parameters.operationResult
+      maxProtocolMessageBytes: this.#maxProtocolMessageBytes,
+      hasLogSink: this.#forwardedLogGate.hasSink
     };
-    if (this.#maxProtocolMessageBytes !== void 0)
-      message.maxProtocolMessageBytes = this.#maxProtocolMessageBytes;
-    return message;
   }
   cancelWorkflow(workflowId) {
     const worker = this.#ownership.getActiveWorker(workflowId);
@@ -205,6 +201,12 @@ export class WorkerExecutionStrategy {
     this.#messageHandler = null;
   }
   async#handleWorkerMessage(worker, message) {
+    if (isWorkerLogMessage(message)) {
+      const owns = (id) => this.#ownership.getTargetWorker(id) === worker, abuseDiscard = this.#forwardedLogGate.handle(worker, message, owns);
+      if (abuseDiscard)
+        this.#discardWorkerAndFailWorkflows(worker, abuseDiscard);
+      return;
+    }
     if (!this.#acceptWorkerMessage(worker, message))
       return;
     this.#turnWatchdog.clear(worker);
@@ -322,6 +324,7 @@ export class WorkerExecutionStrategy {
     const workflowIds = this.#ownership.workflowIdsForWorker(worker);
     if (workflowIds.length === 0) {
       this.#turnWatchdog.clear(worker);
+      this.#forwardedLogGate.forget(worker);
       return;
     }
     for (const workflowId of workflowIds) {
@@ -338,6 +341,7 @@ export class WorkerExecutionStrategy {
       });
     }
     this.#turnWatchdog.clear(worker);
+    this.#forwardedLogGate.forget(worker);
     this.#workerListeners.detach(worker);
     this.#pool.discard(worker);
   }