@lostgradient/weft 0.2.1 → 0.4.0

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

@@ -0,0 +1,136 @@
+import { KEYS } from "../../storage/interface.js";
+import { AtomicState, atomicStateVersionKey, readAtomicStateSnapshot } from "../atomic-state.js";
+import { decode, encode } from "../codec.js";
+import {
+  initialLockRecord,
+  reduceRelease
+} from "../concurrency.js";
+import { WorkflowConcurrencyLimitExceededError } from "./errors.js";
+const WORKFLOW_CONCURRENCY_HOLDER_VERSION = 1, NON_EXPIRING_WORKFLOW_CONCURRENCY_LEASE = Number.MAX_SAFE_INTEGER;
+function encodeVersionCondition(dataKey, version) {
+  return {
+    key: atomicStateVersionKey(dataKey),
+    expectedValue: version === 0 ? null : encode(version)
+  };
+}
+function normalizeLockRecord(record) {
+  if (record === void 0)
+    return initialLockRecord();
+  return {
+    holders: Array.isArray(record.holders) ? record.holders : [],
+    waiters: Array.isArray(record.waiters) ? record.waiters : []
+  };
+}
+function liveWorkflowConcurrencyHolders(holders, now) {
+  return holders.filter((holder) => holder.leaseExpiresAt > now);
+}
+function acquireWorkflowConcurrencySlot(current, options) {
+  const record = normalizeLockRecord(current), holders = liveWorkflowConcurrencyHolders(record.holders, options.now);
+  if (holders.some((holder) => holder.holderId === options.workflowId))
+    return {
+      acquired: !0,
+      record: {
+        holders: holders.map((holder) => holder.holderId === options.workflowId ? {
+          holderId: options.workflowId,
+          leaseExpiresAt: NON_EXPIRING_WORKFLOW_CONCURRENCY_LEASE
+        } : holder),
+        waiters: []
+      }
+    };
+  if (holders.length >= options.limit)
+    return { acquired: !1, record: { holders, waiters: [] } };
+  return {
+    acquired: !0,
+    record: {
+      holders: [
+        ...holders,
+        {
+          holderId: options.workflowId,
+          leaseExpiresAt: NON_EXPIRING_WORKFLOW_CONCURRENCY_LEASE
+        }
+      ],
+      waiters: []
+    }
+  };
+}
+function resolveWorkflowConcurrencyPartitionKey(workflowType, input, concurrency) {
+  if (concurrency.key === void 0)
+    return workflowType;
+  let partitionKey;
+  try {
+    partitionKey = concurrency.key(input);
+  } catch (error) {
+    throw Error(`workflow("${workflowType}").concurrency.key threw while resolving the partition key: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (typeof partitionKey !== "string")
+    throw TypeError(`workflow("${workflowType}").concurrency.key must return a string partition key`);
+  return partitionKey;
+}
+function encodeHolderRecord(workflowType, partitionKey) {
+  return {
+    version: WORKFLOW_CONCURRENCY_HOLDER_VERSION,
+    workflowType,
+    partitionKey
+  };
+}
+function decodeHolderRecord(bytes) {
+  const decoded = decode(bytes);
+  if (typeof decoded !== "object" || decoded === null)
+    return null;
+  const record = decoded;
+  if (record.version !== WORKFLOW_CONCURRENCY_HOLDER_VERSION || typeof record.workflowType !== "string" || typeof record.partitionKey !== "string")
+    return null;
+  return {
+    version: WORKFLOW_CONCURRENCY_HOLDER_VERSION,
+    workflowType: record.workflowType,
+    partitionKey: record.partitionKey
+  };
+}
+export async function buildWorkflowConcurrencyStartOperations(internals, workflowType, workflowId, input, concurrency) {
+  const partitionKey = resolveWorkflowConcurrencyPartitionKey(workflowType, input, concurrency), stateKey = KEYS.workflowConcurrency(workflowType, partitionKey), snapshot = await readAtomicStateSnapshot(internals.storage, stateKey, {
+    initial: initialLockRecord()
+  }), acquired = acquireWorkflowConcurrencySlot(snapshot.value, {
+    workflowId,
+    now: internals.options.getNow(),
+    limit: concurrency.max
+  });
+  if (!acquired.acquired)
+    throw new WorkflowConcurrencyLimitExceededError({
+      workflowType,
+      limit: concurrency.max,
+      partitionKey
+    });
+  return {
+    stateKey,
+    conditions: [encodeVersionCondition(stateKey, snapshot.version)],
+    operations: [
+      { type: "put", key: stateKey, value: encode(acquired.record) },
+      { type: "put", key: atomicStateVersionKey(stateKey), value: encode(snapshot.version + 1) },
+      {
+        type: "put",
+        key: KEYS.workflowConcurrencyHolder(workflowId),
+        value: encode(encodeHolderRecord(workflowType, partitionKey))
+      },
+      {
+        type: "put",
+        key: KEYS.terminalCleanupNeeded(workflowId),
+        value: new Uint8Array(0)
+      }
+    ]
+  };
+}
+export async function releaseWorkflowConcurrencySlot(internals, workflowId) {
+  const holderKey = KEYS.workflowConcurrencyHolder(workflowId), markerBytes = await internals.storage.get(holderKey);
+  if (markerBytes === null)
+    return;
+  const marker = decodeHolderRecord(markerBytes);
+  if (marker === null) {
+    await internals.storage.delete(holderKey);
+    return;
+  }
+  const stateKey = KEYS.workflowConcurrency(marker.workflowType, marker.partitionKey);
+  await new AtomicState(internals.storage, stateKey, {
+    initial: initialLockRecord()
+  }).update((current) => reduceRelease(current, { holderId: workflowId, now: internals.options.getNow() }));
+  await internals.storage.delete(holderKey);
+}

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

@@ -7,9 +7,11 @@ import type { EngineInternals } from './internals.ts';
  */
 export type WorkflowFeedSelector = 'events' | 'tokens';
 /**
- * Hard-coded stream key for the `tokens` selector. Matches the
- * legacy REST SSE endpoint's key so resumption cursors round-trip
- * across transports.
+ * Hard-coded stream key for the `tokens` selector. Every transport that
+ * exposes the token feed — `engine.getStreamChunks(id, 'tokens')` and the REST
+ * SSE / WebSocket stream-chunk routes layered on it — keys its stored chunks
+ * under this single value, so a resumption cursor issued by one transport
+ * round-trips through another.
  */
 export declare const TOKENS_STREAM_KEY = "tokens";
 /** Record `kind` for every token stream chunk emitted by the feed. */
@@ -24,11 +26,10 @@ export declare const STREAM_CHUNK_KIND = "stream:chunk";
 export declare const COMPACTION_BOUNDARY_KIND = "workflow:compaction-boundary";
 /**
  * A committed workflow-feed record surfaced to subscribers of
- * `subscribeWorkflowFeedCommits()`. Fires after `storage.batch()`
- * (events) or `storage.put()` (tokens) resolves, so replay and live
- * delivery share the same committed sequence authority. The same
- * shape covers both selectors — consumers filter on `selector`
- * before interpreting `payload`.
+ * `subscribeWorkflowFeedCommits()`. Fires after the storage commit resolves, so
+ * replay and live delivery share the same committed sequence authority. The
+ * same shape covers both selectors — consumers filter on `selector` before
+ * interpreting `payload`.
  *
  *   - `events` selector: `kind` is the durable log entry type
  *     (e.g. `'workflow:checkpoint'`). `sequence` / `timestamp` come

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

@@ -1,7 +1,7 @@
 import { EventLog } from "../event-log.js";
 import { readEventLogWatermark } from "./event-log-compaction.js";
 import { workflowFeedListenerKey } from "./state-utilities.js";
-import { loadStoredStreamChunks } from "./stream-chunk-loading.js";
+import { loadStoredStreamChunks, loadStoredStreamTailSequence } from "./stream-chunk-loading.js";
 export const TOKENS_STREAM_KEY = "tokens", STREAM_CHUNK_KIND = "stream:chunk", COMPACTION_BOUNDARY_KIND = "workflow:compaction-boundary";
 export async function* replayWorkflowFeed(internals, workflowId, selector, afterSequence) {
   if (selector === "events") {
@@ -17,6 +17,9 @@ export async function snapshotWorkflowFeedTail(internals, workflowId, selector)
       return head.sequence;
     return (await new EventLog(internals.storage, workflowId).loadHead()).sequence;
   }
+  const tail = await loadStoredStreamTailSequence(internals.storage, workflowId, TOKENS_STREAM_KEY);
+  if (tail !== null)
+    return tail;
   const chunks = await loadStoredStreamChunks(internals.storage, workflowId, TOKENS_STREAM_KEY);
   if (chunks.length === 0)
     return -1;

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,52 +1,59 @@
 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, 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;
     'workflow:cancelled': WorkflowCancelledEvent;
     'workflow:timed-out': WorkflowTimedOutEvent;
     '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;
@@ -68,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);
+}