@lostgradient/weft 0.2.0

package/dist/core/types/search-attributes.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Union of scalar types accepted as search attribute values. Pass when calling
+ * `engine.setAttributes` or in {@link StartOptions.searchAttributes}. The
+ * engine indexes values of these types so callers can filter via
+ * `engine.list({ attributes: [...] })`.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, type SearchAttributeValue } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'order' }).execute(async function* () { return 'shipped'; }));
+ * const handle = await engine.start('order', null, {
+ *   searchAttributes: { region: 'us-east' as SearchAttributeValue },
+ * });
+ * void handle;
+ * ```
+ */
+export type SearchAttributeValue = string | number | boolean | Date | string[];
+export type JsonSchemaPrimitiveType = 'array' | 'boolean' | 'integer' | 'number' | 'string';
+export type StringSearchAttributeDefinition = {
+    type: 'string';
+    format?: string;
+};
+export type NumberSearchAttributeDefinition = {
+    type: 'number' | 'integer';
+};
+export type BooleanSearchAttributeDefinition = {
+    type: 'boolean';
+};
+export type StringArraySearchAttributeDefinition = {
+    type: 'array';
+    items?: StringSearchAttributeDefinition;
+};
+/**
+ * JSON Schema fragment accepted by the search attribute registry. The engine
+ * supports the scalar and string-array shapes it can index today while keeping
+ * definitions compatible with future schema tooling.
+ *
+ * @example
+ * ```ts
+ * import type { SearchAttributeDefinition } from '@lostgradient/weft';
+ *
+ * const createdAt: SearchAttributeDefinition = { type: 'string', format: 'date-time' };
+ * const tags: SearchAttributeDefinition = {
+ *   type: 'array',
+ *   items: { type: 'string' },
+ * };
+ * void createdAt;
+ * void tags;
+ * ```
+ */
+export type SearchAttributeDefinition = BooleanSearchAttributeDefinition | NumberSearchAttributeDefinition | StringArraySearchAttributeDefinition | StringSearchAttributeDefinition;
+export type SearchAttributePrimitiveValueMap = {
+    array: string[];
+    boolean: boolean;
+    integer: number;
+    number: number;
+    string: string;
+};
+export type SearchAttributeValueForDefinition<TDefinition> = TDefinition extends keyof SearchAttributePrimitiveValueMap ? SearchAttributePrimitiveValueMap[TDefinition] : TDefinition extends {
+    type: 'string';
+    format: 'date-time';
+} ? Date : TDefinition extends {
+    type: infer TType;
+} ? TType extends keyof SearchAttributePrimitiveValueMap ? SearchAttributePrimitiveValueMap[TType] : SearchAttributeValue : SearchAttributeValue;
+/**
+ * Named search attribute handle returned by {@link searchAttribute}. The
+ * runtime value carries `name` and a JSON Schema fragment.
+ *
+ * @example
+ * ```ts
+ * import { searchAttribute, type SearchAttributeHandle } from '@lostgradient/weft';
+ *
+ * declare const ctx: {
+ *   setAttribute(attribute: SearchAttributeHandle<string>, value: string): void;
+ * };
+ * const customerId: SearchAttributeHandle<string> = searchAttribute('customerId', 'string');
+ * ctx.setAttribute(customerId, 'cust_123');
+ * ```
+ */
+export interface SearchAttributeHandle<TValue extends SearchAttributeValue = SearchAttributeValue> {
+    name: string;
+    type: JsonSchemaPrimitiveType;
+    format?: string;
+    items?: StringSearchAttributeDefinition;
+    readonly _value?: () => TValue;
+}
+/**
+ * Registry of named search attribute definitions for a workflow type. Each key
+ * is an attribute name; each value is a `SearchAttributeDefinition` describing
+ * the expected type. Pass via the workflow builder's `searchAttributes` option
+ * (or `WorkflowDefinition.searchAttributes` on a hand-rolled definition) so
+ * the engine validates and indexes attributes at runtime.
+ *
+ * @example
+ * ```ts
+ * import { Engine, workflow, type SearchAttributeSchema } from '@lostgradient/weft';
+ *
+ * const schema: SearchAttributeSchema = {
+ *   customerId: { type: 'string' },
+ *   orderValue:  { type: 'number' },
+ *   isPriority:  { type: 'boolean' },
+ * };
+ * const order = workflow({ name: 'order' })
+ *   .searchAttributes(schema)
+ *   .execute(async function* () { return 'ok'; });
+ * const engine = new Engine();
+ * engine.register(order);
+ * void engine;
+ * ```
+ */
+export type SearchAttributeSchema = Record<string, SearchAttributeDefinition>;
+/**
+ * Create a named search attribute definition.
+ *
+ * @example
+ * ```ts
+ * import { searchAttribute } from '@lostgradient/weft';
+ *
+ * const createdAt = searchAttribute('createdAt', { type: 'string', format: 'date-time' });
+ * ```
+ */
+export declare function searchAttribute<const TDefinition extends JsonSchemaPrimitiveType | SearchAttributeDefinition>(name: string, type: TDefinition): SearchAttributeHandle<SearchAttributeValueForDefinition<TDefinition>>;
+export declare function searchAttributeName(attribute: string | {
+    readonly name: string;
+}): string;

package/dist/core/types/search-attributes.js

@@ -0,0 +1,8 @@
+export function searchAttribute(name, type) {
+  if (typeof type === "string")
+    return { name, type };
+  return { name, ...type };
+}
+export function searchAttributeName(attribute) {
+  return typeof attribute === "string" ? attribute : attribute.name;
+}

package/dist/core/types/serializer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pluggable serialization interface for workflow checkpoints and activity
+ * payloads. Implement this to substitute MessagePack with a custom codec
+ * (e.g. CBOR, Protobuf, JSON). Pass an instance to {@link EngineOptions.serializer}.
+ * Switching serializers on an engine with persisted state is a breaking
+ * change — checkpoints written with the previous serializer will fail to
+ * decode. Migrate state explicitly (e.g. read with the old serializer,
+ * re-write with the new) before flipping the option.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type Serializer } from '@lostgradient/weft';
+ *
+ * const jsonSerializer: Serializer = {
+ *   serialize(value) {
+ *     return new TextEncoder().encode(JSON.stringify(value));
+ *   },
+ *   deserialize(bytes) {
+ *     return JSON.parse(new TextDecoder().decode(bytes)) as unknown;
+ *   },
+ * };
+ *
+ * const engine = new Engine({ serializer: jsonSerializer });
+ * void engine;
+ * ```
+ */
+export interface Serializer {
+    serialize(value: unknown): Uint8Array;
+    deserialize(bytes: Uint8Array): unknown;
+}

package/dist/core/types/standard-schema-validate.d.ts

@@ -0,0 +1,113 @@
+import { WeftError } from '../weft-error.ts';
+import type { DefinitionSchema } from './definition-schema.ts';
+/**
+ * Single normalized validation issue with an RFC 6901 JSON Pointer path.
+ *
+ * @example
+ * ```ts
+ * import type { ValidationIssue } from '@lostgradient/weft/json-schema';
+ *
+ * const issue: ValidationIssue = { message: 'Expected a string.', path: '/email' };
+ * void issue;
+ * ```
+ */
+export interface ValidationIssue {
+    readonly message: string;
+    readonly path: string;
+}
+/**
+ * Context fields attached to a {@link StandardSchemaValidationError}, used by
+ * boundary code to translate the runtime-neutral error into transport-specific
+ * fault payloads.
+ *
+ * @example
+ * ```ts
+ * import type { StandardSchemaValidationContext } from '@lostgradient/weft/json-schema';
+ *
+ * const context: StandardSchemaValidationContext = {
+ *   fieldName: 'input',
+ *   operation: 'weft.workflows.start',
+ * };
+ * void context;
+ * ```
+ */
+export interface StandardSchemaValidationContext {
+    readonly fieldName: string;
+    readonly operation?: string;
+}
+/**
+ * Error thrown by {@link validateStandardSchema} when a Standard Schema
+ * validator rejects an input. Carries the originating field name, optional
+ * operation identifier, and the list of issues with RFC 6901 JSON Pointer
+ * paths so transport code can translate it into the right fault shape.
+ *
+ * **Reserved for boundary integration.** Nothing in the engine calls
+ * {@link validateStandardSchema} yet; the runtime validator is exported here
+ * so transport-operation modules and worker dispatch paths can wire it in
+ * during a follow-up. Definition helpers carry schemas as inert metadata
+ * today.
+ *
+ * @example
+ * ```ts
+ * import { StandardSchemaValidationError } from '@lostgradient/weft/json-schema';
+ *
+ * const error = new StandardSchemaValidationError({
+ *   fieldName: 'input',
+ *   operation: 'weft.workflows.start',
+ *   issues: [{ message: 'Expected a string.', path: '/email' }],
+ * });
+ * void error;
+ * ```
+ */
+export declare class StandardSchemaValidationError extends WeftError<'StandardSchemaValidationError'> {
+    readonly fieldName: string;
+    readonly operation: string | undefined;
+    readonly issues: ReadonlyArray<ValidationIssue>;
+    constructor(parameters: {
+        fieldName: string;
+        operation: string | undefined;
+        issues: ReadonlyArray<ValidationIssue>;
+    });
+}
+/**
+ * Validate an unknown input against a {@link DefinitionSchema} that carries a
+ * Standard Schema validator under `~standard`. Awaits async validators. On
+ * success returns the validated value. On failure throws a
+ * {@link StandardSchemaValidationError} whose issue paths are RFC 6901 JSON
+ * Pointers. Throws a {@link TypeError} when the schema only carries a JSON
+ * Schema converter (no runtime validator).
+ *
+ * **Reserved for boundary integration.** This helper is exported for use by
+ * transport-operation modules and worker-side activity dispatch paths during
+ * boundary validation work. Nothing in the engine calls it today; the
+ * definition helpers' schemas are inert metadata until that wiring lands.
+ *
+ * @example
+ * ```ts
+ * import { validateStandardSchema } from '@lostgradient/weft/json-schema';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({ email: z.string().email() });
+ * const valid = await validateStandardSchema(schema, { email: 'a@b.co' }, {
+ *   fieldName: 'input',
+ * });
+ * void valid;
+ * ```
+ */
+export declare function validateStandardSchema<Output>(schema: DefinitionSchema<unknown, Output>, input: unknown, context: StandardSchemaValidationContext): Promise<Output>;
+/**
+ * Format an array of {@link ValidationIssue} values as a single
+ * newline-separated string. Useful in tests and developer logs.
+ *
+ * @example
+ * ```ts
+ * import { formatStandardSchemaIssues } from '@lostgradient/weft/json-schema';
+ *
+ * const formatted = formatStandardSchemaIssues([
+ *   { message: 'Expected a string.', path: '/email' },
+ * ]);
+ * // "/email: Expected a string."
+ * void formatted;
+ * ```
+ */
+export declare function formatStandardSchemaIssues(issues: ReadonlyArray<ValidationIssue>): string;

package/dist/core/types/standard-schema-validate.js

@@ -0,0 +1,60 @@
+import { WeftError } from "../weft-error.js";
+
+export class StandardSchemaValidationError extends WeftError {
+  fieldName;
+  operation;
+  issues;
+  constructor(parameters) {
+    super("StandardSchemaValidationError", buildErrorMessage(parameters.fieldName, parameters.operation, parameters.issues));
+    this.fieldName = parameters.fieldName;
+    this.operation = parameters.operation;
+    this.issues = parameters.issues;
+  }
+}
+export async function validateStandardSchema(schema, input, context) {
+  const standardProperties = schema["~standard"];
+  if (!hasValidator(standardProperties))
+    throw TypeError(`Schema for ${context.fieldName} does not provide runtime validation. Attach a Standard Schema validator (Zod, Valibot, or another vendor) or supply a runtime-validating schema at this boundary.`);
+  const result = await standardProperties.validate(input);
+  if (result.issues === void 0)
+    return result.value;
+  throw new StandardSchemaValidationError({
+    fieldName: context.fieldName,
+    operation: context.operation,
+    issues: result.issues.map(toValidationIssue)
+  });
+}
+export function formatStandardSchemaIssues(issues) {
+  return issues.map((issue) => issue.path === "" ? issue.message : `${issue.path}: ${issue.message}`).join(`
+`);
+}
+function hasValidator(properties) {
+  return typeof properties.validate === "function";
+}
+function toValidationIssue(issue) {
+  return { message: issue.message, path: encodeJsonPointer(issue.path) };
+}
+function encodeJsonPointer(path) {
+  if (path === void 0 || path.length === 0)
+    return "";
+  let pointer = "";
+  for (const segment of path) {
+    pointer += "/";
+    pointer += encodeSegment(segment);
+  }
+  return pointer;
+}
+function encodeSegment(segment) {
+  const key = isPathSegment(segment) ? segment.key : segment;
+  return escapeJsonPointerToken(String(key));
+}
+function isPathSegment(value) {
+  return value !== null && typeof value === "object" && "key" in value;
+}
+function escapeJsonPointerToken(token) {
+  return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function buildErrorMessage(fieldName, operation, issues) {
+  return `Validation failed for ${operation === void 0 ? fieldName : `${operation} ${fieldName}`}:
+${formatStandardSchemaIssues(issues)}`;
+}

package/dist/core/types/state.d.ts

@@ -0,0 +1,261 @@
+import type { AtomicStateOptions } from '../atomic-state.ts';
+import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+import type { ActivityCallOptions } from './activity.ts';
+import type { CheckpointState } from './checkpoint.ts';
+import type { TerminationReason } from './history-policy.ts';
+import type { FailureCategory, WorkflowId, WorkflowStatus } from './identity.ts';
+import type { WorkflowOperation } from './workflow-function.ts';
+/**
+ * Snapshot of a workflow's persisted state.
+ *
+ * Returned by `handle.state()` and `engine.get(workflowId)`. Users observe
+ * this shape — they don't construct it. Includes the input, current status,
+ * attributes, retention policy snapshot, and lineage information,
+ * plus `failureCategory` (populated on failed workflows), version tuple
+ * metadata, `forkedFrom` lineage metadata, and the optional
+ * `executionDeadline`/`terminalCleanupToken` housekeeping fields.
+ */
+export interface WorkflowState {
+    id: WorkflowId;
+    type: string;
+    status: WorkflowStatus;
+    tags?: string[];
+    input: unknown;
+    result?: unknown;
+    error?: string;
+    errorStack?: string;
+    /**
+     * Classifies why this workflow failed. Populated automatically on failure;
+     * absent (`undefined`) on workflows that have not failed. `null` indicates
+     * a failure occurred but the category could not be determined.
+     *
+     * Also indexed as a search attribute so callers can query via:
+     * `engine.list({ attributes: [{ key: 'failureCategory', value: 'application' }] })`
+     */
+    failureCategory?: FailureCategory | null;
+    /**
+     * Distinct reason a workflow reached its terminal state, beyond the
+     * {@link WorkflowStatus} itself. Currently populated only when the history
+     * circuit breaker forces a workflow to `timed-out`
+     * ({@link HISTORY_CIRCUIT_BREAKER_REASON}), letting operators tell
+     * circuit-breaker termination apart from an ordinary deadline timeout (which
+     * leaves this `undefined`).
+     */
+    terminationReason?: TerminationReason;
+    version: string;
+    /**
+     * Owner identifier for execution-scoped durable state. Top-level workflows
+     * own their own execution state; durable child workflows inherit the
+     * parent's owner so `ctx.state.execution()` is shared across the execution
+     * tree.
+     */
+    executionStateOwnerId?: string;
+    /**
+     * Legacy version tuple metadata retained so existing persisted workflow
+     * states can still be decoded and compared during recovery.
+     */
+    agentVersion?: string;
+    /**
+     * Legacy version tuple metadata retained so existing persisted workflow
+     * states can still be decoded and compared during recovery.
+     */
+    toolVersions?: string[];
+    createdAt: number;
+    startedAt?: number;
+    updatedAt: number;
+    terminalCleanupToken?: string;
+    executionDeadline?: number;
+    /**
+     * Lineage metadata recorded when this workflow was created by a fork from
+     * another workflow checkpoint. Absent for workflows started normally.
+     */
+    forkedFrom?: ForkLineage;
+}
+/**
+ * Lineage metadata recorded when a workflow was created by forking another
+ * workflow at a checkpoint boundary. Absent on workflows started normally via
+ * {@link Engine.start}. Available on {@link WorkflowState.forkedFrom}.
+ */
+export interface ForkLineage {
+    workflowId: WorkflowId;
+    step: number;
+}
+/**
+ * Status of an individual entry in the workflow execution timeline. Mirrors
+ * {@link WorkflowStatus} but scoped to a single timeline step rather than the
+ * whole workflow. Used in {@link WorkflowTimelineEntry}.
+ */
+export type WorkflowTimelineStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'timed-out';
+/**
+ * A single chronological entry in a workflow's execution timeline, summarising
+ * one operation (activity call, sleep, signal wait, etc.). Returned by
+ * `engine.getTimeline(workflowId)` for replay and debugging.
+ * The optional `versionTuple` field is populated only for entries produced by
+ * versioned workflows and carries the version tuple captured at the time of
+ * the operation.
+ */
+export type WorkflowTimelineEntry = {
+    step: number;
+    operationType: string;
+    operationLabel: string;
+    inputSummary: string;
+    outputSummary?: string;
+    duration?: number;
+    timestamp: number;
+    status: WorkflowTimelineStatus;
+    versionTuple?: WorkflowVersionTuple;
+};
+/**
+ * Options accepted by `ctx.state.session(key, options)`.
+ */
+export interface WorkflowSessionStateOptions<T> {
+    /**
+     * Value returned by `get()` before this session slot has been written.
+     * The value is captured when the handle is constructed.
+     */
+    initial?: T;
+}
+/**
+ * Typed per-workflow session state slot returned by `ctx.state.session(key)`.
+ * Survives checkpoint recovery but is scoped to the current workflow instance.
+ * Use `get` to read the current value, `set` or `update` to write, and `run`
+ * to schedule a sticky durable activity that may need session-bound context.
+ * `delete()` removes the stored value; subsequent `get()` returns the handle's
+ * captured `initial` value if one was provided, otherwise `undefined`.
+ * `run` schedules the function as a regular activity routed through sticky
+ * worker execution. The function receives the single input value you pass to
+ * `run(...)` — it cannot read the slot from inside. Read `session.get()`
+ * before yielding the run if the function needs the current value.
+ */
+export interface WorkflowSessionState<T> {
+    get(): T | undefined;
+    set(value: T): T;
+    update(updater: (current: T | undefined) => T): T;
+    delete(): void;
+    increment(this: WorkflowSessionState<number>, amount?: number): number;
+    decrement(this: WorkflowSessionState<number>, amount?: number): number;
+    merge<TObject extends Record<string, unknown>>(this: WorkflowSessionState<TObject>, patch: Partial<TObject>): TObject;
+    append<TItem>(this: WorkflowSessionState<TItem[]>, item: TItem): TItem[];
+    removeFirst<TItem>(this: WorkflowSessionState<TItem[]>): TItem | undefined;
+    removeLast<TItem>(this: WorkflowSessionState<TItem[]>): TItem | undefined;
+    run<TResult>(fn: () => Promise<TResult> | TResult, options?: ActivityCallOptions): WorkflowOperation<TResult>;
+    run<TInput, TResult>(fn: (input: TInput) => Promise<TResult> | TResult, input: TInput, options?: ActivityCallOptions): WorkflowOperation<TResult>;
+}
+/**
+ * Options accepted by storage-backed workflow state handles such as
+ * `ctx.state.execution(key, options)` and `ctx.state.workflow(key, options)`.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowAtomicStateOptions } from '@lostgradient/weft';
+ *
+ * const options: WorkflowAtomicStateOptions<number> = {
+ *   initial: 0,
+ *   maxRetries: 5,
+ * };
+ * void options;
+ * ```
+ */
+export type WorkflowAtomicStateOptions<T> = Pick<AtomicStateOptions<T>, 'initial' | 'maxRetries'>;
+/**
+ * Typed storage-backed workflow state slot returned by durable
+ * `ctx.state.*` factories.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowAtomicState } from '@lostgradient/weft';
+ *
+ * declare const counter: WorkflowAtomicState<number>;
+ * const operation = counter.increment();
+ * void operation;
+ * ```
+ */
+export interface WorkflowAtomicState<T> {
+    get(): WorkflowOperation<T | undefined>;
+    set(value: T): WorkflowOperation<T>;
+    update(updater: (current: T | undefined) => T): WorkflowOperation<T>;
+    delete(): WorkflowOperation<void>;
+    increment(this: WorkflowAtomicState<number>, amount?: number): WorkflowOperation<number>;
+    decrement(this: WorkflowAtomicState<number>, amount?: number): WorkflowOperation<number>;
+    merge<TObject extends Record<string, unknown>>(this: WorkflowAtomicState<TObject>, patch: Partial<TObject>): WorkflowOperation<TObject>;
+    append<TItem>(this: WorkflowAtomicState<TItem[]>, item: TItem): WorkflowOperation<TItem[]>;
+    removeFirst<TItem>(this: WorkflowAtomicState<TItem[]>): WorkflowOperation<TItem | undefined>;
+    removeLast<TItem>(this: WorkflowAtomicState<TItem[]>): WorkflowOperation<TItem | undefined>;
+    addEventListener(type: 'change' | 'conflict' | 'exhausted', listener: EventListener): void;
+    removeEventListener(type: 'change' | 'conflict' | 'exhausted', listener: EventListener): void;
+}
+/**
+ * State factory namespace exposed as `ctx.state` inside workflow code.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowStateNamespace } from '@lostgradient/weft';
+ *
+ * declare const state: WorkflowStateNamespace;
+ * const session = state.session<number>('attempts', { initial: 0 });
+ * const durable = state.execution<number>('branches', { initial: 0, maxRetries: 5 });
+ * void session;
+ * void durable;
+ * ```
+ */
+export interface WorkflowStateNamespace {
+    session<T>(key: string, options?: WorkflowSessionStateOptions<T>): WorkflowSessionState<T>;
+    execution<T>(key: string, options?: WorkflowAtomicStateOptions<T>): WorkflowAtomicState<T>;
+    workflow<T>(key: string, options?: WorkflowAtomicStateOptions<T>): WorkflowAtomicState<T>;
+}
+/**
+ * Lightweight summary of a workflow returned by list operations. Contains
+ * identity and lifecycle fields but not the full input, result, or checkpoint.
+ * Use {@link Engine.get} to retrieve the complete {@link WorkflowState}. The
+ * optional fields (`executionDeadline` and `failureCategory`) are populated
+ * whenever the underlying `WorkflowState`
+ * carries them. For failed workflows missing a state category, `failureCategory`
+ * can also be backfilled from stored search attributes when list callers
+ * explicitly request it. Notably absent from the summary: `input`, `result`,
+ * `error`, and `forkedFrom` — fetch the full `WorkflowState` via
+ * `engine.get(id)` to access those.
+ */
+export interface WorkflowSummary {
+    id: WorkflowId;
+    type: string;
+    status: WorkflowStatus;
+    tags?: string[];
+    version: string;
+    createdAt: number;
+    updatedAt: number;
+    /** Execution deadline (ms epoch) if set on the workflow. */
+    executionDeadline?: number;
+    /** Failure category if set on the workflow state. */
+    failureCategory?: FailureCategory;
+}
+/**
+ * Event entries returned by `engine.getEvents()` are stored records — use
+ * `engine.addEventListener(type, handler)` with the typed `Event` subclasses
+ * (e.g. `WorkflowCompletedEvent`) for live observation; the stored `data` map
+ * is provided for replay/audit.
+ */
+export interface WorkflowEvent {
+    type: string;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+/**
+ * Full replay package for a workflow step, combining the checkpoint state,
+ * the accumulated operation results up to that step, and the event log.
+ * Returned by `engine.replayTo(workflowId, step)` for time-travel debugging.
+ */
+export type WorkflowReplay = {
+    checkpoint: CheckpointState;
+    accumulatedResults: Array<[number, unknown]>;
+    events: WorkflowEvent[];
+    /**
+     * Lowest event sequence still present in the log, set whenever event-log
+     * compaction has truncated earlier records (i.e. a watermark exists). When
+     * present, `events` omits the `[0, compactedBefore)` prefix regardless of the
+     * requested step — an inspection caller can use this to tell an incomplete
+     * replay from a complete one. Absent when nothing was compacted. Workflow
+     * execution state always rebuilds fully from `checkpoint`; only the event
+     * slice is bounded.
+     */
+    compactedBefore?: number;
+};