@lostgradient/weft 0.2.0

package/dist/core/engine/construction.js

@@ -0,0 +1,213 @@
+import { AlertManager } from "../../alerting/alert-manager.js";
+import { CompressedStorage } from "../../storage/compressed-storage.js";
+import { MemoryStorage } from "../../storage/memory.js";
+import { ActivityWorkerDispatcher } from "../../workers/activity-worker-dispatcher.js";
+import { WorkerPool } from "../../workers/pool.js";
+import { InlineExecutionStrategy } from "../inline-execution-strategy.js";
+import {
+  DEFAULT_RETENTION_SWEEP_BATCH_SIZE,
+  DEFAULT_RETENTION_SWEEP_INTERVAL_MS
+} from "../types.js";
+import { WorkerExecutionStrategy } from "../worker-execution-strategy.js";
+import {
+  DEFAULT_WORKER_PROTOCOL_MESSAGE_BYTES,
+  DEFAULT_WORKER_TURN_TIMEOUT_MS,
+  MIN_WORKER_PROTOCOL_MESSAGE_BYTES
+} from "../worker-protocol.js";
+import {
+  normalizeHistoryPolicy,
+  normalizePayloadSizePolicy,
+  normalizeRetentionDuration,
+  normalizeRetentionPolicy
+} from "./validation.js";
+export function definitionEntries(definitions) {
+  return Object.entries(definitions ?? {});
+}
+export function typedEngineView(engine, _phantomTypes) {
+  return engine;
+}
+let didWarnOnMemoryStorageFallback = !1;
+function readEnvironmentVariable(name) {
+  return readEnvironmentVariableFromSources(name, {
+    bunEnv: typeof Bun < "u" ? Bun.env : void 0,
+    processEnv: typeof process < "u" ? process.env : void 0
+  });
+}
+export function readEnvironmentVariableFromSources(name, sources) {
+  if (sources.bunEnv !== void 0)
+    return sources.bunEnv[name];
+  if (sources.processEnv !== void 0)
+    return sources.processEnv[name];
+  return;
+}
+function shouldWarnOnMemoryStorageFallback(options) {
+  return options?.development === !0 || readEnvironmentVariable("WEFT_DEV_WARNINGS") === "1" || readEnvironmentVariable("NODE_ENV") === "development";
+}
+export function resetMemoryStorageFallbackWarningForTesting() {
+  didWarnOnMemoryStorageFallback = !1;
+}
+export function resolveEngineStorage(options) {
+  let baseStorage = options?.storage ?? void 0;
+  if (baseStorage === void 0) {
+    if (!didWarnOnMemoryStorageFallback && shouldWarnOnMemoryStorageFallback(options)) {
+      didWarnOnMemoryStorageFallback = !0;
+      console.warn("[weft] Engine started with no `storage` configured \u2014 falling back to MemoryStorage. " + "Workflow state is held only in memory and is lost when the process exits, so a crash or restart discards every in-flight workflow. Pass a durable adapter (e.g. SQLiteStorage) via `new Engine({ storage })` for anything beyond tests and local dev. (This warning appears only in development.)");
+    }
+    baseStorage = new MemoryStorage;
+  }
+  if (!options?.compression)
+    return baseStorage;
+  return new CompressedStorage(baseStorage, options.compression);
+}
+export function resolveEngineInterceptors(options) {
+  return options?.interceptors ? [...options.interceptors] : [];
+}
+export function copyWorkflowDefinition(type, registration) {
+  return {
+    type,
+    version: registration.version,
+    tags: registration.tags === void 0 ? [] : [...registration.tags],
+    ...registration.description === void 0 ? {} : { description: registration.description },
+    ...registration.inputSchema === void 0 ? {} : { inputSchema: registration.inputSchema },
+    ...registration.outputSchema === void 0 ? {} : { outputSchema: registration.outputSchema },
+    ...registration.searchAttributes === void 0 ? {} : { searchAttributes: registration.searchAttributes }
+  };
+}
+function resolveRetentionFields(options) {
+  return {
+    retention: normalizeRetentionPolicy(options?.retention, "options.retention"),
+    retentionSweepIntervalMs: normalizeRetentionDuration(options?.retentionSweepInterval, "options.retentionSweepInterval") ?? DEFAULT_RETENTION_SWEEP_INTERVAL_MS,
+    retentionSweepBatchSize: options?.retentionSweepBatchSize !== void 0 ? Math.max(1, Math.floor(options.retentionSweepBatchSize)) : DEFAULT_RETENTION_SWEEP_BATCH_SIZE
+  };
+}
+function defaultTo(value, fallback) {
+  return value ?? fallback;
+}
+function resolveBooleanDefaults(options) {
+  return {
+    development: defaultTo(options?.development, !1),
+    broadcastEvents: defaultTo(options?.broadcastEvents, !1)
+  };
+}
+function resolveNumericDefaults(options) {
+  return {
+    checkpointHistory: defaultTo(options?.checkpointHistory, 10),
+    checkpointSizeWarningThreshold: defaultTo(options?.checkpointSizeWarningThreshold, 65536),
+    maxNestingDepth: defaultTo(options?.maxNestingDepth, 10)
+  };
+}
+function resolveHistoryFields(options) {
+  return {
+    historyPolicy: normalizeHistoryPolicy(options?.history, "options.history"),
+    archiveAdapter: options?.archive ?? null,
+    payloadSizePolicy: normalizePayloadSizePolicy(options?.payloadSize, "options.payloadSize")
+  };
+}
+export function resolveEngineOptions(storage, options, getNow) {
+  return {
+    storage,
+    getNow,
+    ...resolveBooleanDefaults(options),
+    ...resolveNumericDefaults(options),
+    ...resolveRetentionFields(options),
+    ...resolveHistoryFields(options)
+  };
+}
+export function normalizeWorkerExecutionConfiguration(options) {
+  const workflowExecutionMode = normalizeWorkflowExecutionMode(options?.workflowExecutionMode), workerExecution = resolveWorkerExecutionForMode(options, workflowExecutionMode);
+  if (!workerExecution)
+    return { mode: "inline", workerExecution: null };
+  return normalizeWorkerModeConfiguration(workerExecution);
+}
+function normalizeWorkflowExecutionMode(value) {
+  if (value === void 0 || value === "inline" || value === "worker")
+    return value;
+  throw Error('options.workflowExecutionMode must be "inline" or "worker" when provided');
+}
+function resolveWorkerExecutionForMode(options, workflowExecutionMode) {
+  if (workflowExecutionMode === "inline") {
+    if (options?.workerExecution !== void 0)
+      throw Error('options.workerExecution cannot be provided when workflowExecutionMode is "inline"');
+    return null;
+  }
+  if (workflowExecutionMode === "worker") {
+    if (options?.workerExecution === void 0)
+      throw Error('options.workerExecution is required when workflowExecutionMode is "worker"');
+    return options.workerExecution;
+  }
+  if (options?.workerExecution !== void 0)
+    throw Error('options.workflowExecutionMode must be "worker" when options.workerExecution is provided');
+  return null;
+}
+function normalizeWorkerModeConfiguration(workerExecution) {
+  const workflowTurnTimeoutMs = normalizePositiveSafeIntegerOption(workerExecution.workflowTurnTimeoutMs, "options.workerExecution.workflowTurnTimeoutMs", void 0) ?? DEFAULT_WORKER_TURN_TIMEOUT_MS, maxProtocolMessageBytes = normalizePositiveSafeIntegerOption(workerExecution.maxProtocolMessageBytes, "options.workerExecution.maxProtocolMessageBytes", void 0) ?? DEFAULT_WORKER_PROTOCOL_MESSAGE_BYTES;
+  if (maxProtocolMessageBytes < MIN_WORKER_PROTOCOL_MESSAGE_BYTES)
+    throw Error(`options.workerExecution.maxProtocolMessageBytes must be at least ${MIN_WORKER_PROTOCOL_MESSAGE_BYTES}`);
+  return {
+    mode: "worker",
+    workerExecution,
+    workflowTurnTimeoutMs,
+    maxProtocolMessageBytes,
+    requireProtocolVersion: !0,
+    discardOnCancel: !0
+  };
+}
+function normalizePositiveSafeIntegerOption(value, fieldName, defaultValue) {
+  if (value === void 0)
+    return defaultValue;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+    throw Error(`${fieldName} must be a positive safe integer when provided`);
+  return value;
+}
+export function createExecutionStrategyBundle(parameters) {
+  const {
+    options,
+    getNow,
+    maxNestingDepth,
+    development,
+    broadcastEvents,
+    getRegistration,
+    getComposedWorkflowInterceptor,
+    resolveWorkflowType,
+    registerCancelHandler
+  } = parameters, workerExecutionConfiguration = normalizeWorkerExecutionConfiguration(options);
+  if (workerExecutionConfiguration.mode === "worker") {
+    const pool = new WorkerPool({
+      workerUrl: workerExecutionConfiguration.workerExecution.workerUrl,
+      concurrency: workerExecutionConfiguration.workerExecution.poolSize ?? 4,
+      smol: workerExecutionConfiguration.workerExecution.smol ?? !1
+    }), strategyOptions = {
+      broadcastEvents,
+      requireProtocolVersion: workerExecutionConfiguration.requireProtocolVersion,
+      discardOnCancel: workerExecutionConfiguration.discardOnCancel,
+      workflowTurnTimeoutMs: workerExecutionConfiguration.workflowTurnTimeoutMs,
+      maxProtocolMessageBytes: workerExecutionConfiguration.maxProtocolMessageBytes
+    };
+    return {
+      strategy: new WorkerExecutionStrategy(pool, strategyOptions),
+      inlineStrategy: null
+    };
+  }
+  const inlineStrategy = new InlineExecutionStrategy({
+    getRegistration,
+    ...getComposedWorkflowInterceptor !== void 0 && { getComposedWorkflowInterceptor },
+    getNow,
+    maxNestingDepth,
+    development,
+    resolveWorkflowType,
+    ...registerCancelHandler !== void 0 && { registerCancelHandler }
+  });
+  return { strategy: inlineStrategy, inlineStrategy };
+}
+export function createActivityWorkerDispatcher(activityExecution) {
+  if (!activityExecution)
+    return null;
+  return new ActivityWorkerDispatcher(new WorkerPool({
+    workerUrl: activityExecution.workerUrl,
+    concurrency: activityExecution.poolSize ?? 4,
+    smol: activityExecution.smol ?? !1
+  }));
+}
+export function createAlertManagerForEngine(engine, alerts, getNow) {
+  return alerts ? new AlertManager(engine, alerts, getNow) : null;
+}

package/dist/core/engine/disposal.d.ts

@@ -0,0 +1,9 @@
+import type { EngineInternals } from './internals.ts';
+/**
+ * Synchronous teardown for an {@link Engine}. Moved verbatim from
+ * `Engine[Symbol.dispose]` — the operation order is correctness-sensitive
+ * (abort before clearing waiters, dispose strategies before nulling them) and
+ * is preserved exactly. `Engine[Symbol.dispose]` and `[Symbol.asyncDispose]`
+ * both delegate here.
+ */
+export declare function disposeEngine(internals: EngineInternals): void;

package/dist/core/engine/disposal.js

@@ -0,0 +1,58 @@
+import { disposeEngineCleanupInterval } from "./engine-runtime-helpers.js";
+import { EngineDisposedError } from "./errors.js";
+import { disposeQueuedInlineWorkflowStarts } from "./inline-launch-queue.js";
+export function disposeEngine(internals) {
+  internals.disposed = !0;
+  internals.alertManager?.[Symbol.dispose]();
+  internals.alertManager = null;
+  internals.abortController.abort();
+  for (const resolveSignalWaiter of internals.signalWaiters.values())
+    resolveSignalWaiter();
+  internals.signalWaiters.clear();
+  internals.signalWaitersByWorkflow.clear();
+  disposeQueuedInlineWorkflowStarts(internals);
+  internals.scheduler[Symbol.dispose]();
+  internals.strategy[Symbol.dispose]();
+  internals.activityWorkerDispatcher?.[Symbol.dispose]();
+  internals.activityWorkerDispatcher = null;
+  internals.inlineStrategy = null;
+  disposeEngineCleanupInterval(internals);
+  if (internals.retentionSweepInterval !== null) {
+    clearInterval(internals.retentionSweepInterval ?? void 0);
+    internals.retentionSweepInterval = null;
+  }
+  internals.nextRetentionSweepAt = null;
+  internals.handleCache.clear();
+  for (const waiter of internals.resultResolvers.values())
+    waiter.reject(new EngineDisposedError);
+  internals.resultResolvers.clear();
+  internals.updateWaiters.clear();
+  internals.updateWaitersByWorkflow.clear();
+  internals.reviewWaiters.clear();
+  internals.reviewWaitersByWorkflow.clear();
+  internals.reviewEscalationHandlers.clear();
+  internals.workflowReviewIds.clear();
+  internals.parkedInlineWorkflows.clear();
+  internals.terminalizingWorkflows.clear();
+  internals.reviewTimerIds.clear();
+  for (const controller of internals.pendingWebhooks)
+    controller.abort();
+  internals.pendingWebhooks.clear();
+  internals.sleepResolvers.clear();
+  internals.sleepResolversByWorkflow.clear();
+  internals.checkpoints.clear();
+  internals.pendingExecutionStateOwnerId = void 0;
+  internals.workflowNestingDepths.clear();
+  internals.workflowHeaders.clear();
+  internals.pendingStarts.clear();
+  internals.pendingScheduleCreations.clear();
+  internals.eventLogHeads.clear();
+  internals.pendingTimelineEntries.clear();
+  internals.workflowVersionTuples.clear();
+  internals.workflowFeedListeners.clear();
+  internals.activityRegistriesByWorkflow.clear();
+  internals.workflowDefinitionsByName.clear();
+  internals.workflowTypeByWorkflowId.clear();
+  internals.broadcastChannel?.close();
+  internals.broadcastChannel = null;
+}

package/dist/core/engine/engine-create-types.d.ts

@@ -0,0 +1,70 @@
+import type { AnyActivityDefinition, AnyWorkflowDefinition, IsDefaultWorkflowRegistry } from '../types.ts';
+import type { UnknownNameWhenRegistryHasNoKnownNames } from '../types/registry-type-helpers.ts';
+import type { KnownWorkflowNames } from './construction.ts';
+import type { EngineConstructorOptions } from './engine-internal-types.ts';
+/**
+ * Options accepted by `Engine.create`. Definition maps are used for type
+ * inference, then each map key is checked against the definition's runtime
+ * `name` before registration.
+ *
+ * @example
+ * ```ts
+ * import { activity, Engine, workflow, type EngineCreateOptions } from '@lostgradient/weft';
+ *
+ * const greet = activity({ name: 'greet', execute: async (name: string) => `Hello, ${name}` });
+ * const welcome = workflow({ name: 'welcome' }).execute(async function* (ctx, input: string) {
+ *   return yield* ctx.run(greet, input);
+ * });
+ *
+ * const options = {
+ *   workflows: { welcome },
+ *   activities: { greet },
+ * } satisfies EngineCreateOptions<{ welcome: typeof welcome }, { greet: typeof greet }>;
+ * const engine = await Engine.create(options);
+ * void engine;
+ * ```
+ */
+export type EngineCreateOptions<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition> = {}, TActivityDefinitions extends Record<string, AnyActivityDefinition> = {}> = EngineConstructorOptions & {
+    /** Workflow definitions to register before recovery. */
+    workflows?: TWorkflowDefinitions;
+    /** Activity definitions to register before workflows. */
+    activities?: TActivityDefinitions;
+    /**
+     * Opt out of the persisted-data schema-version gate when opening a storage
+     * that contains workflow data written by `new Engine({ storage })` before
+     * the schema-version sentinel existed.
+     *
+     * The gate normally rejects any storage that already holds workflow records
+     * but lacks the sentinel — a safety check against silently classifying
+     * pre-sentinel data as schema-current. Set `allowLegacyData: true` only when
+     * you knowingly opened the same storage with the legacy constructor path and
+     * are intentionally recovering it via `Engine.create`. On success, the
+     * current schema-version sentinel is written. Remove the opt-in once the
+     * data has been migrated.
+     */
+    allowLegacyData?: boolean;
+} & ({
+    /**
+     * Recover stored running workflows after registration. Defaults to
+     * `true`: a fresh engine booting against durable storage resumes any
+     * workflows left in flight by a previous process. Pass `recover: false`
+     * to opt out (tests, `ScopedStorage` isolation, pre-migration
+     * inspection).
+     */
+    recover?: true | undefined;
+    /**
+     * Forwarded to `Engine.recoverAll`. Only use this during rolling
+     * deploys or explicit storage migrations.
+     */
+    acknowledgeUnknownWorkflowTypes?: boolean;
+} | {
+    /** Opt out of recovering stored running workflows after registration. */
+    recover: false;
+    /** Only valid when recovery is enabled (the default). Invalid with `recover: false`. */
+    acknowledgeUnknownWorkflowTypes?: never;
+});
+export type UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows extends object, TName extends string> = IsDefaultWorkflowRegistry<TWorkflows> extends true ? UnknownNameWhenRegistryHasNoKnownNames<TName, KnownWorkflowNames<TWorkflows>> : never;
+export type ActivityDefinitionName<TDefinition extends AnyActivityDefinition> = TDefinition extends {
+    readonly name: infer TName extends string;
+} ? TName : string;
+export type RegisteredActivityDefinitionExecute<TActivities extends object, TName extends Extract<keyof TActivities, string>> = TActivities[TName] extends (...arguments_: infer TArguments) => infer TResult ? (...arguments_: TArguments) => Awaited<TResult> | Promise<Awaited<TResult>> : never;

package/dist/core/engine/engine-internal-types.d.ts

@@ -0,0 +1,59 @@
+import type { Storage as WeftStorage } from '../../storage/interface.ts';
+import type { ConstraintDefinition } from '../constraint.ts';
+import type { ExecutionStrategy } from '../execution-strategy.ts';
+import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
+import type { ArchiveAdapter, Checkpoint, DefinitionSchema, EngineOptions, NormalizedHistoryPolicy, NormalizedPayloadSizePolicy, NormalizedRetentionPolicy, SearchAttributeSchema, WorkflowFunction, WorkflowTimelineEntry } from '../types.ts';
+export interface RegistrationEntry {
+    handler: WorkflowFunction;
+    version: string;
+    description?: string;
+    tags?: ReadonlyArray<string>;
+    inputSchema?: DefinitionSchema;
+    outputSchema?: DefinitionSchema;
+    migrate?: (checkpoint: unknown, fromVersion: string) => unknown;
+    searchAttributes?: SearchAttributeSchema;
+    retention?: NormalizedRetentionPolicy;
+    constraints?: ConstraintDefinition[];
+}
+export interface ResolvedOptions {
+    storage: WeftStorage;
+    development: boolean;
+    checkpointHistory: number;
+    checkpointSizeWarningThreshold: number;
+    maxNestingDepth: number;
+    broadcastEvents: boolean;
+    retention: NormalizedRetentionPolicy | null;
+    retentionSweepIntervalMs: number;
+    retentionSweepBatchSize: number;
+    historyPolicy: NormalizedHistoryPolicy;
+    /** Operator-supplied sink for compacted event-log ranges; `null` when none. */
+    archiveAdapter: ArchiveAdapter | null;
+    payloadSizePolicy: NormalizedPayloadSizePolicy;
+    getNow: () => number;
+}
+export interface WorkflowResultWaiter {
+    promise: Promise<unknown>;
+    resolve: (value: unknown) => void;
+    reject: (reason: unknown) => void;
+}
+export type EngineConstructorOptions = Partial<EngineOptions> & {
+    getNow?: () => number;
+};
+export type ExecutionStrategyBundle = {
+    strategy: ExecutionStrategy;
+    inlineStrategy: InlineExecutionStrategy | null;
+};
+export type TrackedWaiterKeys = string | Set<string>;
+export type PendingTimelineEntry = {
+    startedAt: number;
+    entry: WorkflowTimelineEntry;
+};
+export type QueuedInlineWorkflowExecutionStart = {
+    workflowId: string;
+    workflowType: string;
+    input: unknown;
+    checkpoint: Checkpoint;
+    nestingDepth: number;
+    executionDeadline: number | undefined;
+    executionStateOwnerId: string;
+};

package/dist/core/engine/engine-leak-warnings.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Test-only state and helpers for the engine cleanup-interval finalizer
+ * leak-warning system. Kept in a sibling module so `index.ts` does not
+ * accumulate test-only ceremony.
+ */
+export type EngineCleanupIntervalDisposalTracker = {
+    disposed: boolean;
+    cleanupInterval: ReturnType<typeof setInterval> | null;
+    testToken: symbol | undefined;
+};
+export declare const engineCleanupIntervalFinalizer: FinalizationRegistry<EngineCleanupIntervalDisposalTracker>;
+export declare function shouldEmitEngineLeakWarning(): boolean;
+/** Test-only override for the engine leak-warning environment gate. */
+export declare function setEngineLeakWarningOverrideForTesting(value: boolean | undefined): void;
+/** Test-only marker applied to the next constructed engine leak tracker. */
+export declare function setNextEngineLeakWarningTokenForTesting(value: symbol | undefined): void;
+/** Read the test-only next-token marker, consuming it. */
+export declare function consumeNextEngineLeakWarningTokenForTesting(): symbol | undefined;
+/** Test-only count of engine cleanup finalizer observations. */
+export declare function getEngineLeakCollectionCountForTesting(): number;
+/** Test-only visibility into whether a tagged engine leak emitted a warning. */
+export declare function hasEngineLeakWarningTokenForTesting(token: symbol): boolean;
+/** Test-only cleanup for tagged leak warning observations. */
+export declare function clearEngineLeakWarningTokenForTesting(token: symbol): void;
+/** Test-only visibility into the engine leak-warning environment gate. */
+export declare function shouldEmitEngineLeakWarningForTesting(): boolean;

package/dist/core/engine/engine-leak-warnings.js

@@ -0,0 +1,42 @@
+let engineLeakWarningOverrideForTesting, engineLeakCollectionCountForTesting = 0, nextEngineLeakWarningTokenForTesting;
+const engineLeakWarningTokensForTesting = new Set;
+export const engineCleanupIntervalFinalizer = new FinalizationRegistry((tracker) => {
+  engineLeakCollectionCountForTesting++;
+  if (tracker.cleanupInterval !== null) {
+    clearInterval(tracker.cleanupInterval);
+    tracker.cleanupInterval = null;
+  }
+  if (!tracker.disposed && shouldEmitEngineLeakWarning()) {
+    if (tracker.testToken !== void 0)
+      engineLeakWarningTokensForTesting.add(tracker.testToken);
+    process.emitWarning("WeftEngineLeakWarning: A Weft Engine was garbage-collected without calling [Symbol.dispose](). Use `using`, `await using`, or call engine[Symbol.dispose]() to clear background timers and release runtime resources.");
+  }
+});
+export function shouldEmitEngineLeakWarning() {
+  if (engineLeakWarningOverrideForTesting !== void 0)
+    return engineLeakWarningOverrideForTesting;
+  return Bun.env.WEFT_DEV_WARNINGS === "1" || Bun.env.NODE_ENV === "development";
+}
+export function setEngineLeakWarningOverrideForTesting(value) {
+  engineLeakWarningOverrideForTesting = value;
+}
+export function setNextEngineLeakWarningTokenForTesting(value) {
+  nextEngineLeakWarningTokenForTesting = value;
+}
+export function consumeNextEngineLeakWarningTokenForTesting() {
+  const token = nextEngineLeakWarningTokenForTesting;
+  nextEngineLeakWarningTokenForTesting = void 0;
+  return token;
+}
+export function getEngineLeakCollectionCountForTesting() {
+  return engineLeakCollectionCountForTesting;
+}
+export function hasEngineLeakWarningTokenForTesting(token) {
+  return engineLeakWarningTokensForTesting.has(token);
+}
+export function clearEngineLeakWarningTokenForTesting(token) {
+  engineLeakWarningTokensForTesting.delete(token);
+}
+export function shouldEmitEngineLeakWarningForTesting() {
+  return shouldEmitEngineLeakWarning();
+}

package/dist/core/engine/engine-runtime-helpers.d.ts

@@ -0,0 +1,8 @@
+import type { AnyActivityDefinition } from '../types.ts';
+import { type EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
+import type { Engine } from './index.ts';
+import { type EngineInternals } from './internals.ts';
+export declare function isActivityDefinition(value: unknown): value is AnyActivityDefinition;
+export declare function createQueuedInlineWorkflowStartHandler<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>, channel: MessageChannel): () => void;
+export declare function createCleanupIntervalTick<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>, tracker: EngineCleanupIntervalDisposalTracker): () => void;
+export declare function disposeEngineCleanupInterval(internals: EngineInternals): void;

package/dist/core/engine/engine-runtime-helpers.js

@@ -0,0 +1,52 @@
+import { createExpiredResponseCleanupTick } from "../engine-helpers.js";
+import { createLifecycleCallbacks, createTerminationCallbacks } from "./callback-creators-core.js";
+import {
+  engineCleanupIntervalFinalizer
+} from "./engine-leak-warnings.js";
+import { flushQueuedInlineWorkflowStarts } from "./inline-launch-queue.js";
+import { getInternals } from "./internals.js";
+import { swallowPromiseRejection } from "./strategy-helpers.js";
+export function isActivityDefinition(value) {
+  return typeof value === "function" && typeof value.name === "string" && "execute" in value && typeof value.execute === "function";
+}
+export function createQueuedInlineWorkflowStartHandler(weakEngine, channel) {
+  return function handleQueuedInlineWorkflowStart() {
+    const engine = weakEngine.deref();
+    if (engine === void 0) {
+      channel.port1.close();
+      channel.port2.close();
+      return;
+    }
+    getInternals(engine).queuedInlineWorkflowStartFlushScheduled = !1;
+    swallowPromiseRejection(flushQueuedInlineWorkflowStarts(getInternals(engine), {
+      processPendingUpdatesAfterInlineAdvance: (workflowId) => createLifecycleCallbacks(engine).processPendingUpdatesAfterInlineAdvance(workflowId),
+      swallowPromiseRejection: (promise) => swallowPromiseRejection(promise)
+    }));
+  };
+}
+export function createCleanupIntervalTick(weakEngine, tracker) {
+  return function cleanupExpiredResponsesForLiveEngine() {
+    const engine = weakEngine.deref();
+    if (engine === void 0) {
+      if (tracker.cleanupInterval !== null) {
+        clearInterval(tracker.cleanupInterval);
+        tracker.cleanupInterval = null;
+      }
+      return;
+    }
+    const internals = getInternals(engine);
+    createExpiredResponseCleanupTick(internals.updateCoordinator, (source, error) => createTerminationCallbacks(engine).handleCleanupError(source, error))();
+  };
+}
+export function disposeEngineCleanupInterval(internals) {
+  if (internals.cleanupInterval !== null) {
+    clearInterval(internals.cleanupInterval ?? void 0);
+    internals.cleanupInterval = null;
+  }
+  if (internals.cleanupIntervalDisposalTracker !== null) {
+    internals.cleanupIntervalDisposalTracker.disposed = !0;
+    internals.cleanupIntervalDisposalTracker.cleanupInterval = null;
+    engineCleanupIntervalFinalizer.unregister(internals.cleanupIntervalDisposalTracker);
+    internals.cleanupIntervalDisposalTracker = null;
+  }
+}

package/dist/core/engine/engine-state-namespace.d.ts

@@ -0,0 +1,20 @@
+import type { AtomicState, AtomicStateOptions } from '../atomic-state.ts';
+/**
+ * Admin-facing factories for storage-backed {@link AtomicState} handles.
+ * Workflow code should prefer `ctx.state.*`; external maintenance and
+ * administrative code can use `engine.state.*` with explicit scope inputs.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type EngineStateNamespace } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const state: EngineStateNamespace = engine.state;
+ * const counter = state.workflow<number>('invoice', 'count', { initial: 0 });
+ * void counter;
+ * ```
+ */
+export interface EngineStateNamespace {
+    execution<T>(ownerWorkflowId: string, key: string, options?: AtomicStateOptions<T>): AtomicState<T>;
+    workflow<T>(workflowType: string, key: string, options?: AtomicStateOptions<T>): AtomicState<T>;
+}