@lostgradient/weft 0.3.0 → 0.4.0

package/dist/core/engine/workflow-indexes.d.ts

@@ -14,6 +14,7 @@
 import { type BatchOperation, type Storage } from '../../storage/interface.ts';
 import type { WorkflowState } from '../types.ts';
 import { WeftError } from '../weft-error.ts';
+import type { EngineInternals } from './internals.ts';
 /**
  * Bumped whenever the index layout or population rules change. The engine
  * compares this to the watermark stored at `wf-idx-meta:version` to decide
@@ -96,8 +97,16 @@ export declare function buildWorkflowVisibilityIndexTransition(workflowId: strin
  * consult the new `wf-idx-*` rows when the watermark is `current`.
  */
 export type WorkflowVisibilityWatermark = 'current' | 'stale';
+export declare const WORKFLOW_VISIBILITY_WATERMARK_CACHE_TTL_MS = 1000;
 /**
  * Read the visibility-index watermark. Returns `'current'` when the
  * persisted version is at or above {@link WORKFLOW_VISIBILITY_INDEX_VERSION}.
  */
 export declare function getWorkflowVisibilityWatermark(storage: Storage): Promise<WorkflowVisibilityWatermark>;
+/**
+ * Read the visibility-index watermark through the engine-local query cache.
+ * The short freshness window avoids repeated metadata reads during bursts of
+ * list/aggregate queries without pinning an external backfill or drop decision
+ * until process restart.
+ */
+export declare function getCachedWorkflowVisibilityWatermark(internals: EngineInternals): Promise<WorkflowVisibilityWatermark>;

package/dist/core/engine/workflow-indexes.js

@@ -77,6 +77,7 @@ function buildWorkflowVisibilityIndexOperationsInternal(workflowId, previousKeys
   return { batchOps, nextManifestKeys: nextKeys };
 }
 const EMPTY_INDEX_VALUE = new Uint8Array(0);
+export const WORKFLOW_VISIBILITY_WATERMARK_CACHE_TTL_MS = 1000;
 export async function getWorkflowVisibilityWatermark(storage) {
   const bytes = await storage.get(KEYS.workflowVisibilityMetaVersion());
   if (!bytes)
@@ -91,3 +92,12 @@ export async function getWorkflowVisibilityWatermark(storage) {
     return "stale";
   return payload >= WORKFLOW_VISIBILITY_INDEX_VERSION ? "current" : "stale";
 }
+export async function getCachedWorkflowVisibilityWatermark(internals) {
+  const { workflowVisibilityWatermark: cachedWatermark, workflowVisibilityWatermarkExpiresAt: expiresAt } = internals, now = Date.now();
+  if (cachedWatermark !== void 0 && expiresAt !== void 0 && now < expiresAt)
+    return cachedWatermark;
+  const watermark = await getWorkflowVisibilityWatermark(internals.storage);
+  internals.workflowVisibilityWatermark = watermark;
+  internals.workflowVisibilityWatermarkExpiresAt = now + WORKFLOW_VISIBILITY_WATERMARK_CACHE_TTL_MS;
+  return watermark;
+}

package/dist/core/engine/workflow-state-stream.js

@@ -6,25 +6,35 @@ import {
 import { failureCategorySearchValues, isFailureCategory } from "../failure-categories.js";
 import { encodeAttributeValue, searchAttributeName } from "../search-attributes.js";
 import { normalizeWorkflowTags } from "../workflow-tags.js";
-import { intersectIdentifierSets, matchesListFilter } from "./state-utilities.js";
+import { CONSTRAINED_ID_CHUNK_SIZE } from "./candidate-read-batching.js";
+import {
+  attributeFilterExactValues,
+  decodeSearchAttributeRecord,
+  intersectIdentifierSets,
+  listFilterHasAttributeFilters,
+  matchesListFilter
+} from "./state-utilities.js";
 import { decodeWorkflowState } from "./validation.js";
 const ATTRIBUTE_SCAN_CONCURRENCY = 8;
 export async function* streamMatchingWorkflowStates(internals, filter) {
   const normalizedTagFilters = normalizeWorkflowTags(filter?.tags), constrainedIds = await resolveConstrainedIds(internals, filter, normalizedTagFilters);
   if (constrainedIds !== null) {
-    for (const workflowId of constrainedIds) {
-      const state = await loadMatchingWorkflowState(internals, workflowId, filter, constrainedIds, normalizedTagFilters);
-      if (state === null)
-        continue;
-      yield state;
+    const orderedIds = [...constrainedIds];
+    for (let start = 0;start < orderedIds.length; start += CONSTRAINED_ID_CHUNK_SIZE) {
+      const chunkIds = orderedIds.slice(start, start + CONSTRAINED_ID_CHUNK_SIZE), chunkStates = await Promise.all(chunkIds.map((workflowId) => loadMatchingWorkflowState(internals, workflowId, filter, constrainedIds, normalizedTagFilters)));
+      for (const state of chunkStates) {
+        if (state === null)
+          continue;
+        yield state;
+      }
     }
     return;
   }
   for await (const [key, value] of internals.storage.scan("wf:")) {
     if (!isTopLevelWorkflowStateKey(key))
       continue;
-    const state = decodeWorkflowState(value);
-    if (!matchesListFilter(state, filter, constrainedIds, normalizedTagFilters))
+    const state = decodeWorkflowState(value), searchAttributes = await readSearchAttributesForFilter(internals, state.id, filter);
+    if (!matchesListFilter(state, filter, constrainedIds, normalizedTagFilters, searchAttributes))
       continue;
     yield state;
   }
@@ -33,11 +43,16 @@ async function loadMatchingWorkflowState(internals, workflowId, filter, constrai
   const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
   if (!stateBytes)
     return null;
-  const state = decodeWorkflowState(stateBytes);
-  if (!matchesListFilter(state, filter, constrainedIds, normalizedTagFilters))
+  const state = decodeWorkflowState(stateBytes), searchAttributes = await readSearchAttributesForFilter(internals, workflowId, filter);
+  if (!matchesListFilter(state, filter, constrainedIds, normalizedTagFilters, searchAttributes))
     return null;
   return state;
 }
+async function readSearchAttributesForFilter(internals, workflowId, filter) {
+  if (!listFilterHasAttributeFilters(filter))
+    return null;
+  return decodeSearchAttributeRecord(await internals.storage.get(KEYS.attribute(workflowId)));
+}
 export async function resolveConstrainedIds(internals, filter, normalizedTagFilters) {
   const attributeFilters = filter?.attributes, hasAttributeFilters = attributeFilters !== void 0 && attributeFilters.length > 0, hasTagFilters = normalizedTagFilters !== void 0 && normalizedTagFilters.length > 0;
   if (!hasAttributeFilters && !hasTagFilters)
@@ -78,10 +93,15 @@ function requireConstrainedIdSet(idSet) {
   return idSet;
 }
 async function collectExactAttributeMatches(internals, filter, attributeName, ids) {
-  const exactValue = filter.value;
-  if (exactValue === void 0)
+  const exactValues = attributeFilterExactValues(filter);
+  if (exactValues === null)
     return;
-  const values = filter.key === "failureCategory" && isFailureCategory(exactValue) ? failureCategorySearchValues(exactValue) : [exactValue];
+  const values = [];
+  for (const exactValue of exactValues)
+    if (filter.key === "failureCategory" && isFailureCategory(exactValue))
+      values.push(...failureCategorySearchValues(exactValue));
+    else
+      values.push(exactValue);
   for (const value of values) {
     const exactPrefix = `idx:${attributeName}:${encodeAttributeValue(value)}:`;
     for await (const [key] of internals.storage.scan(exactPrefix))

package/dist/core/engine/workflow-visibility-queries.d.ts

@@ -6,13 +6,13 @@
  *
  * Every helper assumes the visibility-index watermark is `current` — the
  * caller checks {@link getWorkflowVisibilityWatermark} once per query and
- * falls back to the legacy scan path when it is `stale`.
+ * uses the current full-scan correctness path when it is `stale`.
  *
  * @module core/engine/workflow-visibility-queries
  */
 import { type Storage } from '../../storage/interface.ts';
 import type { FailureCategory, WorkflowStatus } from '../types/identity.ts';
-import type { TimeRange } from '../types/options.ts';
+import type { TimeRange } from '../types/list-options.ts';
 /**
  * Match every workflow whose `status` appears in `statuses`. Empty input
  * returns an empty set (intersection short-circuits to "no matches").

package/dist/core/engine-helpers.js

@@ -25,6 +25,7 @@ export async function cleanupPartialStreamChunks(storage, workflowId, key, writt
     return;
   const deleteOperations = [
     ...writtenKeys.map((writtenKey) => ({ type: "delete", key: writtenKey })),
+    { type: "delete", key: KEYS.streamTail(workflowId, key) },
     { type: "delete", key: KEYS.streamMetadata(workflowId, key) }
   ];
   await storage.batch(deleteOperations).catch((deleteError) => {

package/dist/core/events/activity-events.d.ts

@@ -8,9 +8,8 @@
  * import { Engine, ActivityStartedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('activity:started', (e: Event) => {
- *   const ev = e as ActivityStartedEvent;
- *   console.log('activity started:', ev.activityName, 'attempt', ev.attempt);
+ * engine.addEventListener(ActivityStartedEvent.type, (event) => {
+ *   console.log('activity started:', event.activityName, 'attempt', event.attempt);
  * });
  * ```
  */
@@ -32,9 +31,8 @@ export declare class ActivityStartedEvent extends Event {
  * import { Engine, ActivityCompletedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('activity:completed', (e: Event) => {
- *   const ev = e as ActivityCompletedEvent;
- *   console.log(ev.activityName, 'completed in', ev.duration, 'ms');
+ * engine.addEventListener(ActivityCompletedEvent.type, (event) => {
+ *   console.log(event.activityName, 'completed in', event.duration, 'ms');
  * });
  * ```
  */
@@ -61,9 +59,8 @@ export declare class ActivityCompletedEvent extends Event {
  * import { Engine, ActivityAsyncPendingEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('activity:async-pending', (e: Event) => {
- *   const ev = e as ActivityAsyncPendingEvent;
- *   console.log('awaiting external completion of', ev.activityName, 'token', ev.token);
+ * engine.addEventListener(ActivityAsyncPendingEvent.type, (event) => {
+ *   console.log('awaiting external completion of', event.activityName, 'token', event.token);
  * });
  * ```
  */
@@ -87,9 +84,8 @@ export declare class ActivityAsyncPendingEvent extends Event {
  * import { Engine, ActivityFailedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('activity:failed', (e: Event) => {
- *   const ev = e as ActivityFailedEvent;
- *   console.error(ev.activityName, 'attempt', ev.attempt, 'failed:', ev.error.message);
+ * engine.addEventListener(ActivityFailedEvent.type, (event) => {
+ *   console.error(event.activityName, 'attempt', event.attempt, 'failed:', event.error.message);
  * });
  * ```
  */
@@ -102,3 +98,38 @@ export declare class ActivityFailedEvent extends Event {
     readonly attempt: number;
     constructor(operationId: string, workflowId: string, activityName: string, error: Error, attempt: number);
 }
+/**
+ * Fired on the {@link Engine} when a remote worker task result cannot be
+ * durably moved from in-flight to resolved after storage retries are exhausted.
+ * The durable dead-letter guard prevents reconciliation from silently
+ * re-dispatching the already-completed worker attempt until an operator clears
+ * the diagnostic entry.
+ *
+ * @example
+ * ```ts
+ * import { Engine, TaskResultDeadLetteredEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(TaskResultDeadLetteredEvent.type, (event) => {
+ *   console.warn('task dead-lettered:', event.operationId, event.reason);
+ * });
+ * ```
+ */
+export declare class TaskResultDeadLetteredEvent extends Event {
+    static readonly type: "task:dead-lettered";
+    readonly operationId: string;
+    readonly workflowId: string | undefined;
+    readonly activityName: string | undefined;
+    readonly queue: string | undefined;
+    readonly workerId: string | undefined;
+    readonly reason: 'result-resolution-storage-exhausted';
+    readonly errorMessage: string;
+    constructor({ operationId, workflowId, activityName, queue, workerId, errorMessage, }: {
+        operationId: string;
+        workflowId?: string | undefined;
+        activityName?: string | undefined;
+        queue?: string | undefined;
+        workerId?: string | undefined;
+        errorMessage: string;
+    });
+}

package/dist/core/events/activity-events.js

@@ -61,3 +61,31 @@ export class ActivityFailedEvent extends Event {
     this.attempt = attempt;
   }
 }
+
+export class TaskResultDeadLetteredEvent extends Event {
+  static type = "task:dead-lettered";
+  operationId;
+  workflowId;
+  activityName;
+  queue;
+  workerId;
+  reason;
+  errorMessage;
+  constructor({
+    operationId,
+    workflowId,
+    activityName,
+    queue,
+    workerId,
+    errorMessage
+  }) {
+    super(TaskResultDeadLetteredEvent.type);
+    this.operationId = operationId;
+    this.workflowId = workflowId;
+    this.activityName = activityName;
+    this.queue = queue;
+    this.workerId = workerId;
+    this.reason = "result-resolution-storage-exhausted";
+    this.errorMessage = errorMessage;
+  }
+}

package/dist/core/events/attribute-events.d.ts

@@ -8,9 +8,8 @@
  * import { Engine, AttributesChangedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('attributes:changed', (e: Event) => {
- *   const ev = e as AttributesChangedEvent;
- *   console.log('attributes changed for', ev.workflowId, ev.changes);
+ * engine.addEventListener(AttributesChangedEvent.type, (event) => {
+ *   console.log('attributes changed for', event.workflowId, event.changes);
  * });
  * ```
  */

package/dist/core/events/event-map.d.ts

@@ -1,30 +1,30 @@
 import type { ReviewCompletedEvent, ReviewRequestedEvent } from '../review/events.ts';
-import type { ActivityAsyncPendingEvent, ActivityCompletedEvent, ActivityFailedEvent, ActivityStartedEvent } from './activity-events.ts';
+import type { ActivityAsyncPendingEvent, ActivityCompletedEvent, ActivityFailedEvent, ActivityStartedEvent, TaskResultDeadLetteredEvent } from './activity-events.ts';
 import type { AttributesChangedEvent } from './attribute-events.ts';
+import type { ScheduleFiredEvent, ScheduleMissedFireEvent } from './schedule-events.ts';
 import type { SignalDeliveredEvent, SignalReceivedEvent } from './signal-events.ts';
-import type { AlertFiredEvent, AlertResolvedEvent, CheckpointSizeWarningEvent, CleanupWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, StorageSizeReportedEvent } from './system-events.ts';
+import type { AlertFiredEvent, AlertResolvedEvent, CheckpointSizeWarningEvent, CleanupWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, StorageSizeReportedEvent, WorkerConnectedEvent, WorkerDisconnectedEvent } from './system-events.ts';
 import type { UpdateCompletedEvent, UpdateReceivedEvent } from './update-events.ts';
-import type { WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowSuspendedEvent, WorkflowTimedOutEvent } from './workflow-events.ts';
+import type { WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowDefinitionRegisteredEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowSuspendedEvent, WorkflowTeardownEvent, WorkflowTimedOutEvent } from './workflow-events.ts';
 /**
  * Record mapping each event-name string the {@link Engine} dispatches to its
- * corresponding typed `Event` subclass. Use this as the type parameter for
- * {@link TypedEventTarget} to get type-safe `addEventListener` /
- * `removeEventListener` on the engine.
+ * corresponding typed `Event` subclass.
  *
  * @example
  * ```ts
- * import { Engine, type TypedEventTarget, type WeftEventMap } from '@lostgradient/weft';
+ * import { Engine, type WeftEventMap } from '@lostgradient/weft';
  *
  * function listenAll(engine: Engine) {
- *   (engine as TypedEventTarget<WeftEventMap>)
- *     .addEventListener('workflow:completed', (e) => {
- *       console.log('done', e.workflowId, e.result);
- *     });
+ *   engine.addEventListener('workflow:completed', (event) => {
+ *     const completed: WeftEventMap['workflow:completed'] = event;
+ *     console.log('done', completed.workflowId, completed.result);
+ *   });
  * }
  * void listenAll;
  * ```
  */
 export type WeftEventMap = {
+    'workflow:definition-registered': WorkflowDefinitionRegisteredEvent;
     'workflow:started': WorkflowStartedEvent;
     'workflow:completed': WorkflowCompletedEvent;
     'workflow:failed': WorkflowFailedEvent;
@@ -33,21 +33,27 @@ export type WeftEventMap = {
     'workflow:resumed': WorkflowResumedEvent;
     'workflow:suspended': WorkflowSuspendedEvent;
     'workflow:recovery-skipped': WorkflowRecoverySkippedEvent;
+    'workflow:teardown': WorkflowTeardownEvent;
     'activity:started': ActivityStartedEvent;
     'activity:completed': ActivityCompletedEvent;
     'activity:failed': ActivityFailedEvent;
     'activity:async-pending': ActivityAsyncPendingEvent;
+    'task:dead-lettered': TaskResultDeadLetteredEvent;
     'signal:received': SignalReceivedEvent;
     'signal:delivered': SignalDeliveredEvent;
+    'schedule:fired': ScheduleFiredEvent;
     'human-review:requested': ReviewRequestedEvent;
     'human-review:completed': ReviewCompletedEvent;
     'attributes:changed': AttributesChangedEvent;
+    'schedule:missed-fire': ScheduleMissedFireEvent;
     'update:received': UpdateReceivedEvent;
     'update:completed': UpdateCompletedEvent;
     'checkpoint:size-warning': CheckpointSizeWarningEvent;
     'development:warning': DevelopmentWarningEvent;
     'cleanup:warning': CleanupWarningEvent;
     'storage:size-reported': StorageSizeReportedEvent;
+    'worker:connected': WorkerConnectedEvent;
+    'worker:disconnected': WorkerDisconnectedEvent;
     'alert:fired': AlertFiredEvent;
     'alert:resolved': AlertResolvedEvent;
     'constraint:violated': ConstraintViolatedEvent;
@@ -69,7 +75,7 @@ export type WeftEventMap = {
  *   });
  * }
  * const engine = new Engine();
- * addTypedListener(engine as TypedEventTarget<WeftEventMap>);
+ * addTypedListener(engine);
  * void engine;
  * ```
  */

package/dist/core/events/index.d.ts

@@ -1,6 +1,7 @@
 export * from './activity-events.ts';
 export * from './attribute-events.ts';
 export * from './event-map.ts';
+export * from './schedule-events.ts';
 export * from './signal-events.ts';
 export * from './system-events.ts';
 export * from './update-events.ts';

package/dist/core/events/index.js

@@ -1,6 +1,7 @@
 export * from "./activity-events.js";
 export * from "./attribute-events.js";
 export * from "./event-map.js";
+export * from "./schedule-events.js";
 export * from "./signal-events.js";
 export * from "./system-events.js";
 export * from "./update-events.js";

package/dist/core/events/schedule-events.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Fired on the {@link Engine} each time a schedule launches an occurrence — i.e.
+ * whenever a scheduled run is actually started, whether that is a fresh cadence
+ * tick, a `cancel-running` replacement, or a `queue`d run draining after the
+ * previous one finished. A fire means a workflow was launched: the blocked
+ * policies (`skip`, and `queue` while a run is already active) intentionally do
+ * **not** emit, since nothing started.
+ *
+ * Delivery is process-local and best-effort — listen via
+ * `engine.addEventListener('schedule:fired', handler)` on the live engine that
+ * owns the schedule. The durable part (the cadence, and the launched run itself)
+ * is handled by the schedule; the event is dispatched synchronously right after
+ * the run's durable start commits, so a crash in that narrow window — start
+ * committed, dispatch not yet reached — can drop the notification without
+ * affecting the run. Treat it as a reaction signal, not a durable record. This
+ * lets a consumer react to a firing without polling `engine.list()` or
+ * `getSchedule()`.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, ScheduleFiredEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener('schedule:fired', (e: Event) => {
+ *   const ev = e as ScheduleFiredEvent;
+ *   console.log('schedule', ev.scheduleId, 'launched run', ev.workflowId);
+ * });
+ * engine.register(workflow({ name: 'tick' }).execute(async function* () { return 'ok'; }));
+ * await engine.schedule('tick', null, { every: '1h' });
+ * ```
+ */
+export declare class ScheduleFiredEvent extends Event {
+    static readonly type: "schedule:fired";
+    /** The schedule whose occurrence fired. */
+    readonly scheduleId: string;
+    /** The workflow run this occurrence launched. */
+    readonly workflowId: string;
+    /** Wall-clock time the run was launched, from the engine's injected clock. */
+    readonly firedAt: number;
+    /**
+     * The scheduled grid timestamp the occurrence was due. `undefined` for a run
+     * that drained from the `queue` overlap policy: a queued occurrence is tracked
+     * only as a count (`queuedRuns`), so its original due timestamp is not retained
+     * and cannot be reported when the run finally launches.
+     */
+    readonly occurrence: number | undefined;
+    constructor(scheduleId: string, workflowId: string, firedAt: number, occurrence?: number);
+}
+/**
+ * Fired on the {@link Engine} when a non-backfill schedule timer is more than
+ * one second late and the engine skips the missed occurrence window instead of
+ * starting workflows for those ticks.
+ *
+ * @example
+ * ```ts
+ * import { Engine, ScheduleMissedFireEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(ScheduleMissedFireEvent.type, (event) => {
+ *   console.warn(event.scheduleId, 'missed', event.missedCount, 'scheduled ticks');
+ * });
+ * ```
+ */
+export declare class ScheduleMissedFireEvent extends Event {
+    static readonly type: "schedule:missed-fire";
+    readonly scheduleId: string;
+    readonly missedCount: number;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    constructor(scheduleId: string, missedCount: number, windowStart: number, windowEnd: number);
+}

package/dist/core/events/schedule-events.js

@@ -0,0 +1,29 @@
+export class ScheduleFiredEvent extends Event {
+  static type = "schedule:fired";
+  scheduleId;
+  workflowId;
+  firedAt;
+  occurrence;
+  constructor(scheduleId, workflowId, firedAt, occurrence) {
+    super(ScheduleFiredEvent.type);
+    this.scheduleId = scheduleId;
+    this.workflowId = workflowId;
+    this.firedAt = firedAt;
+    this.occurrence = occurrence;
+  }
+}
+
+export class ScheduleMissedFireEvent extends Event {
+  static type = "schedule:missed-fire";
+  scheduleId;
+  missedCount;
+  windowStart;
+  windowEnd;
+  constructor(scheduleId, missedCount, windowStart, windowEnd) {
+    super(ScheduleMissedFireEvent.type);
+    this.scheduleId = scheduleId;
+    this.missedCount = missedCount;
+    this.windowStart = windowStart;
+    this.windowEnd = windowEnd;
+  }
+}

package/dist/core/events/signal-events.d.ts

@@ -8,9 +8,8 @@
  * import { Engine, SignalReceivedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('signal:received', (e: Event) => {
- *   const ev = e as SignalReceivedEvent;
- *   console.log(ev.workflowId, 'received signal', ev.signalName);
+ * engine.addEventListener(SignalReceivedEvent.type, (event) => {
+ *   console.log(event.workflowId, 'received signal', event.signalName);
  * });
  * ```
  */
@@ -31,9 +30,8 @@ export declare class SignalReceivedEvent extends Event {
  * import { Engine, SignalDeliveredEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('signal:delivered', (e: Event) => {
- *   const ev = e as SignalDeliveredEvent;
- *   console.log('signal', ev.signalName, 'delivered to', ev.workflowId);
+ * engine.addEventListener(SignalDeliveredEvent.type, (event) => {
+ *   console.log('signal', event.signalName, 'delivered to', event.workflowId);
  * });
  * ```
  */

package/dist/core/events/system-events.d.ts

@@ -9,9 +9,8 @@ import type { ConstraintViolation } from '../constraint.ts';
  * import { Engine, CheckpointSizeWarningEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine({ checkpointSizeWarningThreshold: 32_000 });
- * engine.addEventListener('checkpoint:size-warning', (e: Event) => {
- *   const ev = e as CheckpointSizeWarningEvent;
- *   console.warn(ev.workflowId, 'checkpoint at step', ev.step, 'is', ev.sizeBytes, 'bytes');
+ * engine.addEventListener(CheckpointSizeWarningEvent.type, (event) => {
+ *   console.warn(event.workflowId, 'checkpoint at step', event.step, 'is', event.sizeBytes, 'bytes');
  * });
  * ```
  */
@@ -33,9 +32,8 @@ export declare class CheckpointSizeWarningEvent extends Event {
  * import { Engine, DevelopmentWarningEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine({ development: true });
- * engine.addEventListener('development:warning', (e: Event) => {
- *   const ev = e as DevelopmentWarningEvent;
- *   console.warn('[dev]', ev.message, 'paths:', ev.fieldPaths);
+ * engine.addEventListener(DevelopmentWarningEvent.type, (event) => {
+ *   console.warn('[dev]', event.message, 'paths:', event.fieldPaths);
  * });
  * ```
  */
@@ -63,9 +61,8 @@ export declare class CleanupWarningEvent extends Event {
  * import { Engine, StorageSizeReportedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('storage:size-reported', (e: Event) => {
- *   const ev = e as StorageSizeReportedEvent;
- *   console.log('total storage:', ev.sizeBytes, 'bytes');
+ * engine.addEventListener(StorageSizeReportedEvent.type, (event) => {
+ *   console.log('total storage:', event.sizeBytes, 'bytes');
  * });
  * ```
  */
@@ -74,6 +71,22 @@ export declare class StorageSizeReportedEvent extends Event {
     readonly sizeBytes: number;
     constructor(sizeBytes: number);
 }
+/** Fired when a remote worker successfully registers with the server runtime. */
+export declare class WorkerConnectedEvent extends Event {
+    static readonly type: "worker:connected";
+    readonly workerId: string;
+    readonly queue: string;
+    readonly activities: readonly string[];
+    readonly concurrency: number;
+    constructor(workerId: string, queue: string, activities: readonly string[], concurrency: number);
+}
+/** Fired when a registered remote worker is removed after disconnect handling. */
+export declare class WorkerDisconnectedEvent extends Event {
+    static readonly type: "worker:disconnected";
+    readonly workerId: string;
+    readonly inFlightTaskCount: number;
+    constructor(workerId: string, inFlightTaskCount: number);
+}
 /**
  * Fired on the {@link Engine} when a built-in alert metric breaches its
  * threshold. Read `e.metric`, `e.threshold`, `e.currentValue`, and
@@ -84,9 +97,8 @@ export declare class StorageSizeReportedEvent extends Event {
  * import { Engine, AlertFiredEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('alert:fired', (e: Event) => {
- *   const ev = e as AlertFiredEvent;
- *   console.warn('alert fired:', ev.metric, 'current:', ev.currentValue, 'threshold:', ev.threshold);
+ * engine.addEventListener(AlertFiredEvent.type, (event) => {
+ *   console.warn('alert fired:', event.metric, 'current:', event.currentValue, 'threshold:', event.threshold);
  * });
  * ```
  */
@@ -108,9 +120,8 @@ export declare class AlertFiredEvent extends Event {
  * import { Engine, AlertResolvedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('alert:resolved', (e: Event) => {
- *   const ev = e as AlertResolvedEvent;
- *   console.log('alert resolved:', ev.metric, 'value back to', ev.currentValue);
+ * engine.addEventListener(AlertResolvedEvent.type, (event) => {
+ *   console.log('alert resolved:', event.metric, 'value back to', event.currentValue);
  * });
  * ```
  */
@@ -132,10 +143,9 @@ export declare class AlertResolvedEvent extends Event {
  * import { Engine, ConstraintViolatedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('constraint:violated', (e: Event) => {
- *   const ev = e as ConstraintViolatedEvent;
- *   console.warn('constraint', ev.constraintName, 'violated in', ev.workflowId,
- *     'action:', ev.onViolation);
+ * engine.addEventListener(ConstraintViolatedEvent.type, (event) => {
+ *   console.warn('constraint', event.constraintName, 'violated in', event.workflowId,
+ *     'action:', event.onViolation);
  * });
  * ```
  */

package/dist/core/events/system-events.js

@@ -46,6 +46,32 @@ export class StorageSizeReportedEvent extends Event {
   }
 }
 
+export class WorkerConnectedEvent extends Event {
+  static type = "worker:connected";
+  workerId;
+  queue;
+  activities;
+  concurrency;
+  constructor(workerId, queue, activities, concurrency) {
+    super(WorkerConnectedEvent.type);
+    this.workerId = workerId;
+    this.queue = queue;
+    this.activities = activities;
+    this.concurrency = concurrency;
+  }
+}
+
+export class WorkerDisconnectedEvent extends Event {
+  static type = "worker:disconnected";
+  workerId;
+  inFlightTaskCount;
+  constructor(workerId, inFlightTaskCount) {
+    super(WorkerDisconnectedEvent.type);
+    this.workerId = workerId;
+    this.inFlightTaskCount = inFlightTaskCount;
+  }
+}
+
 export class AlertFiredEvent extends Event {
   static type = "alert:fired";
   metric;