@lostgradient/weft 0.2.0

package/dist/core/types/workflow-builder-helpers.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Type-level helpers consumed by the workflow builder
+ * (`src/core/types/workflow-builder.ts`) and by the per-workflow
+ * `WorkflowContext` overloads (Phase 1b).
+ *
+ * Split out from `workflow-builder.ts` so each file stays under the project's
+ * 500-line guideline and so engine plumbing in later phases can import the
+ * normalised activity/signal/update/query shapes without dragging in the
+ * builder interface itself.
+ */
+import type { ActivityCallable, ActivityContext, ActivityDefinition } from './activity.ts';
+import type { QueryDefinition, SignalDefinition, UpdateDefinition } from './message-handles.ts';
+/**
+ * Object form accepted by `.activities({ ... })`. The outer object key is the
+ * canonical activity name; the inner `name` field is forbidden because passing
+ * one that disagrees with the key is the most common authoring mistake. All
+ * other `ActivityDefinition` options (`retry`, `timeout`, `idempotent`,
+ * `queue`, `description`, `tags`, schemas, `compensate`, `verify`, etc.) are
+ * passed through unchanged.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityObjectInput } from '@lostgradient/weft';
+ *
+ * const entry: ActivityObjectInput<string, string> = {
+ *   execute: async (greeting) => `hello ${greeting}`,
+ *   idempotent: true,
+ * };
+ * void entry;
+ * ```
+ */
+export type ActivityObjectInput<TInput = unknown, TOutput = unknown> = Omit<ActivityDefinition<TInput, TOutput>, 'name'>;
+/** Detect the object form (has `execute`) from a bare callable. */
+type HasExecuteProperty<T> = T extends {
+    execute: unknown;
+} ? true : false;
+/**
+ * Accepted shapes for a single entry in the `.activities({ ... })` map.
+ *
+ * - Bare async or sync function with a single input parameter (or no
+ *   parameters, for void-input activities).
+ * - `ActivityCallable<TInput, TOutput>` returned by `activity({ name, execute })`.
+ * - Object form carrying `execute` plus optional `retry`, `timeout`,
+ *   `idempotent`, etc.
+ *
+ * The constraint is intentionally loose: a single union of three structural
+ * shapes (function, callable-shaped, has-execute-object). Tightening it to
+ * fixed-input-type unions (`(input: never) => unknown`) triggers
+ * contravariance errors that prevent the most common authoring forms from
+ * satisfying `extends ActivityMapInput`. `NormalizeActivities<T>` reads the
+ * concrete input/output types off each entry directly via conditional
+ * inference, so the looser constraint does not cost us downstream typing.
+ *
+ * Multi-parameter functions are allowed by the constraint but degrade
+ * gracefully to `unknown` input in `NormalizeActivities<T>` — they cannot
+ * be reliably called via `ctx.run('name', input)` and that is documented.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityEntryInput } from '@lostgradient/weft';
+ *
+ * const entry: ActivityEntryInput = async (name: string) => `hello ${name}`;
+ * void entry;
+ * ```
+ */
+export type ActivityEntryInput = ((...arguments_: never[]) => unknown) | {
+    readonly execute: (...arguments_: never[]) => unknown;
+};
+/**
+ * The map shape `.activities({ ... })` accepts. Each value is an
+ * `ActivityEntryInput`; the outer object key becomes the activity's canonical
+ * name.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityMapInput } from '@lostgradient/weft';
+ *
+ * const map: ActivityMapInput = {
+ *   greet: async (name: string) => `hello ${name}`,
+ * };
+ * void map;
+ * ```
+ */
+export type ActivityMapInput = Record<string, ActivityEntryInput>;
+/**
+ * Single entry in the normalised activity map. Inputs and outputs are extracted
+ * from the user-provided form so downstream type helpers
+ * (`ActivityArgsFor`, `ActivityResultFor`) can read them uniformly without
+ * re-discriminating between bare functions and object forms.
+ *
+ * The `definition` field stores an untyped `ActivityDefinition` (generic
+ * defaults of `unknown`) so the entry remains assignable across input/output
+ * variations. Type-safety is preserved via the phantom `input`/`output`
+ * marker fields, which `ActivityArgsFor`/`ActivityResultFor` consume.
+ *
+ * @example
+ * ```ts
+ * import type { NormalizedActivityEntry } from '@lostgradient/weft';
+ *
+ * type GreetEntry = NormalizedActivityEntry<{ name: string }, string>;
+ * declare const entry: GreetEntry;
+ * void entry.definition;
+ * ```
+ */
+export interface NormalizedActivityEntry<TInput = unknown, TOutput = unknown> {
+    /** Phantom marker — never read at runtime; carries the input type for ctx.run typing. */
+    readonly input?: TInput;
+    /** Phantom marker — never read at runtime; carries the output type for ctx.run typing. */
+    readonly output?: TOutput;
+    readonly definition: ActivityDefinition;
+}
+/**
+ * The shape stored on a built `WorkflowDefinition` after `.activities({...})`
+ * is consumed. Each entry exposes the inferred input/output types and the
+ * normalised `ActivityDefinition` object that runtime code installs into the
+ * per-workflow activity registry.
+ *
+ * @example
+ * ```ts
+ * import { workflow, type ActivityMap } from '@lostgradient/weft';
+ *
+ * const built = workflow({ name: 'demo' })
+ *   .activities({ greet: async (name: string) => `hello ${name}` })
+ *   .execute(async function* () { return 'ok'; });
+ * const activities: ActivityMap = built.activities as unknown as ActivityMap;
+ * void activities;
+ * ```
+ */
+export type ActivityMap = Record<string, NormalizedActivityEntry>;
+/**
+ * Maps each entry in a user-supplied `ActivityMapInput` to a
+ * `NormalizedActivityEntry`. Input/output inference rules:
+ *
+ * - Bare zero-arg function `() => TOutput | Promise<TOutput>`:
+ *   `input = void`, `output = Awaited<TOutput>`.
+ * - Bare single-arg function `(input: TInput) => TOutput | Promise<TOutput>`:
+ *   `input = TInput`, `output = Awaited<TOutput>`.
+ * - `ActivityCallable<TInput, TOutput>`: same as the underlying definition.
+ * - Object form `{ execute, ...options }`: `execute`'s signature drives inference.
+ * * Multi-parameter functions fall through to `unknown` inputs, which makes
+ * `ctx.run('name', wrongType)` lose type-safety — type tests in Phase 1c pin
+ * this rejection so users see a clear error rather than silent `unknown` drift.
+ *
+ * @example
+ * ```ts
+ * import type { NormalizeActivities } from '@lostgradient/weft';
+ *
+ * type Greet = NormalizeActivities<{ greet: (name: string) => Promise<string> }>;
+ * declare const greet: Greet['greet'];
+ * void greet;
+ * ```
+ */
+export type NormalizeActivities<T extends ActivityMapInput> = {
+    [K in keyof T & string]: NormalizeActivityEntry<T[K]>;
+};
+type NormalizeActivityEntry<T extends ActivityEntryInput> = HasExecuteProperty<T> extends true ? T extends {
+    execute: (input: infer TInput, context?: ActivityContext) => infer TOutput;
+} ? NormalizedActivityEntry<NormalizedInputType<TInput>, Awaited<TOutput>> : T extends {
+    execute: (...arguments_: infer _Args) => infer TOutput;
+} ? NormalizedActivityEntry<unknown, Awaited<TOutput>> : NormalizedActivityEntry : T extends ActivityCallable<infer TInput, infer TOutput> ? NormalizedActivityEntry<TInput, TOutput> : T extends () => infer TOutput ? NormalizedActivityEntry<void, Awaited<TOutput>> : T extends (input: infer TInput) => infer TOutput ? NormalizedActivityEntry<NormalizedInputType<TInput>, Awaited<TOutput>> : NormalizedActivityEntry;
+/**
+ * `never` in a contravariant position can swallow the inferred type; normalize
+ * it back to `unknown` so downstream `ActivityArgsFor` produces a usable
+ * argument shape rather than the unsatisfiable `[input: never]`.
+ */
+type NormalizedInputType<T> = [T] extends [never] ? unknown : T;
+/**
+ * Argument tuple for `ctx.run('name', ...args)`. Collapses to `[]` for `void`
+ * inputs; preserves `[] | [input]` for optional inputs so both zero-arg and
+ * single-arg call shapes typecheck; otherwise `[input: T]`.
+ *
+ * @example
+ * ```ts
+ * import { workflow, type ActivityArgsFor, type ActivityMap } from '@lostgradient/weft';
+ *
+ * const greet = workflow({ name: 'greet' })
+ *   .activities({ formatGreeting: async (name: string) => `hello ${name}` })
+ *   .execute(async function* () { return 'ok'; });
+ *
+ * type Activities = NonNullable<typeof greet._activities>;
+ * type Args = ActivityArgsFor<Activities['formatGreeting']>;
+ * const args: Args = ['hi'];
+ * void args;
+ * void (null as unknown as ActivityMap);
+ * ```
+ */
+export type ActivityArgsFor<TEntry extends NormalizedActivityEntry> = TEntry extends NormalizedActivityEntry<infer TInput> ? [TInput] extends [void] ? [] : undefined extends TInput ? [] | [input: Exclude<TInput, undefined>] : [input: TInput] : [];
+/**
+ * Result type for `ctx.run('name', ...)`. Always `Awaited<TOutput>` so workflow
+ * code never sees a bare `Promise`.
+ *
+ * @example
+ * ```ts
+ * import { workflow, type ActivityResultFor } from '@lostgradient/weft';
+ *
+ * const greet = workflow({ name: 'greet' })
+ *   .activities({ formatGreeting: async (name: string) => `hello ${name}` })
+ *   .execute(async function* () { return 'ok'; });
+ *
+ * type Activities = NonNullable<typeof greet._activities>;
+ * type Result = ActivityResultFor<Activities['formatGreeting']>;
+ * const result: Result = 'hello';
+ * void result;
+ * ```
+ */
+export type ActivityResultFor<TEntry extends NormalizedActivityEntry> = TEntry extends NormalizedActivityEntry<unknown, infer TOutput> ? Awaited<TOutput> : unknown;
+/**
+ * Lookup type for `ctx.waitForSignal('name')`. Extracts the payload type from a
+ * `SignalDefinition` stored on the workflow's signal map.
+ *
+ * @example
+ * ```ts
+ * import { signal, type SignalPayload } from '@lostgradient/weft';
+ *
+ * const approve = signal<{ approverId: string }>('approve');
+ * type ApprovePayload = SignalPayload<typeof approve>;
+ * const payload: ApprovePayload = { approverId: 'user-1' };
+ * void payload;
+ * ```
+ */
+export type SignalPayload<TSignal> = TSignal extends SignalDefinition<infer TInput> ? TInput : unknown;
+/**
+ * Lookup type for `ctx.waitForUpdate('name')`. Extracts the payload + response
+ * shape from a `UpdateDefinition`.
+ *
+ * @example
+ * ```ts
+ * import { update, type UpdatePayload } from '@lostgradient/weft';
+ *
+ * const checkStatus = update<{ id: string }, { status: string }>('checkStatus');
+ * type CheckPayload = UpdatePayload<typeof checkStatus>;
+ * declare const shape: CheckPayload;
+ * shape.respond({ status: 'pending' });
+ * void shape.payload.id;
+ * ```
+ */
+export type UpdatePayload<TUpdate> = TUpdate extends UpdateDefinition<infer TInput, infer TOutput> ? {
+    payload: TInput;
+    respond: (result: TOutput) => void;
+} : {
+    payload: unknown;
+    respond: (result: unknown) => void;
+};
+/**
+ * Lookup type for query handlers registered on a workflow. Returns the
+ * `{ input, output }` pair so handler signatures stay symmetrical with the
+ * other message kinds.
+ *
+ * @example
+ * ```ts
+ * import { query, type QueryShape } from '@lostgradient/weft';
+ *
+ * const getProgress = query<void, number>('getProgress');
+ * type Shape = QueryShape<typeof getProgress>;
+ * const example: Shape = { input: undefined, output: 0.5 };
+ * void example;
+ * ```
+ */
+export type QueryShape<TQuery> = TQuery extends QueryDefinition<infer TInput, infer TOutput> ? {
+    input: TInput;
+    output: TOutput;
+} : {
+    input: unknown;
+    output: unknown;
+};
+/**
+ * Map shape stored on the workflow definition after `.signals({...})`.
+ *
+ * @example
+ * ```ts
+ * import { signal, type SignalMap } from '@lostgradient/weft';
+ *
+ * const map: SignalMap = { approve: signal<{ approverId: string }>('approve') };
+ * void map;
+ * ```
+ */
+export type SignalMap = Record<string, {
+    readonly name: string;
+}>;
+/**
+ * Map shape stored on the workflow definition after `.updates({...})`.
+ *
+ * @example
+ * ```ts
+ * import { update, type UpdateMap } from '@lostgradient/weft';
+ *
+ * const map: UpdateMap = {
+ *   checkStatus: update<{ id: string }, { status: string }>('checkStatus'),
+ * };
+ * void map;
+ * ```
+ */
+export type UpdateMap = Record<string, {
+    readonly name: string;
+}>;
+/**
+ * Map shape stored on the workflow definition after `.queries({...})`.
+ *
+ * @example
+ * ```ts
+ * import { query, type QueryMap } from '@lostgradient/weft';
+ *
+ * const map: QueryMap = { getProgress: query<void, number>('getProgress') };
+ * void map;
+ * ```
+ */
+export type QueryMap = Record<string, {
+    readonly name: string;
+}>;
+export {};

package/dist/core/types/workflow-builder-runtime.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Runtime implementation for the chained workflow builder. The class and its
+ * normalisation helpers live in this file so `workflow-function.ts` stays
+ * inside the 500-line lint ceiling. Phase 2 owns this file; Phase 3 reads the
+ * resulting `BuiltWorkflowDefinition` shape via the type imports.
+ */
+import type { ConstraintDefinition } from '../constraint.ts';
+import { WeftError } from '../weft-error.ts';
+import type { DefinitionSchema } from './definition-schema.ts';
+import type { RetentionPolicy } from './retry-retention.ts';
+import type { SearchAttributeSchema } from './search-attributes.ts';
+import type { ActivityMap, ActivityMapInput, QueryMap, SignalMap, UpdateMap } from './workflow-builder-helpers.ts';
+import type { BuiltWorkflowDefinition } from './workflow-builder.ts';
+import type { WorkflowFunction } from './workflow-function.ts';
+/**
+ * Thrown by the chained workflow builder for runtime invariants that the type
+ * system cannot reliably catch — duplicate chain calls, key/name collisions
+ * inside `.activities({ ... })`, method calls after `.execute()` has run, and
+ * `.execute()` being called twice. Throwing a named error class (rather than a
+ * bare `Error`) makes the failure greppable and tests can pin behaviour
+ * precisely.
+ *
+ * @example
+ * ```ts
+ * import { workflow, WorkflowBuilderError } from '@lostgradient/weft';
+ *
+ * const builder = workflow({ name: 'demo' }).activities({ ping: async () => 'pong' });
+ * try {
+ *   // Re-calling `.activities()` after it's already been set throws at runtime.
+ *   (builder as unknown as { activities: (map: object) => unknown }).activities({
+ *     pong: async () => 'ping',
+ *   });
+ * } catch (error) {
+ *   if (error instanceof WorkflowBuilderError) {
+ *     // duplicate `.activities()` call rejected at runtime.
+ *     void error.message;
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowBuilderError extends WeftError<'WorkflowBuilderError'> {
+    constructor(message: string);
+}
+/**
+ * Initial options accepted by the builder-form `workflow({ name, ... })` call.
+ * Extra metadata fields (`version`, `description`, `tags`, `retention`,
+ * `inputSchema`, `outputSchema`, `migrate`, `constraints`) are passed through
+ * onto the returned {@link BuiltWorkflowDefinition} when `.execute(fn)` runs.
+ * Only `name` is required.
+ *
+ * @example
+ * ```ts
+ * import { workflow, type WorkflowBuilderOptions } from '@lostgradient/weft';
+ *
+ * const options: WorkflowBuilderOptions<'welcome'> = {
+ *   name: 'welcome',
+ *   description: 'Greets a new user.',
+ * };
+ * const welcome = workflow(options).execute(async function* () { return 'ok'; });
+ * void welcome;
+ * ```
+ */
+export interface WorkflowBuilderOptions<TName extends string = string> {
+    name: TName;
+    version?: string;
+    description?: string;
+    tags?: ReadonlyArray<string>;
+    retention?: RetentionPolicy;
+    constraints?: ConstraintDefinition[];
+    migrate?: (checkpoint: unknown, fromVersion: string) => unknown;
+    inputSchema?: DefinitionSchema<unknown, unknown>;
+    outputSchema?: DefinitionSchema<unknown, unknown>;
+    /**
+     * Explicitly forbidden: `workflow({ name }).execute(handler)` is the only
+     * way to attach a handler. The builder rejects an in-options `handler`
+     * field so the chained `.execute()` step is the single source of truth.
+     */
+    handler?: never;
+}
+/**
+ * Runtime implementation backing the {@link WorkflowBuilder} type. The class
+ * is intentionally private to the module graph — callers always receive it
+ * through {@link workflow} and type-narrow to `WorkflowBuilder` so the
+ * phantom-flag state machine prevents duplicate chain calls at compile time.
+ * The runtime mirrors the same invariants with state flags so misuse from
+ * untyped JavaScript still throws.
+ */
+export declare class WorkflowBuilderImpl<TName extends string> {
+    #private;
+    constructor(options: WorkflowBuilderOptions<TName>);
+    activities: (map: ActivityMapInput) => this;
+    signals: (map: SignalMap) => this;
+    updates: (map: UpdateMap) => this;
+    queries: (map: QueryMap) => this;
+    searchAttributes: (schema: SearchAttributeSchema) => this;
+    execute: (fn: WorkflowFunction) => BuiltWorkflowDefinition<unknown, unknown, TName, ActivityMap, SignalMap, UpdateMap, QueryMap, SearchAttributeSchema>;
+}

package/dist/core/types/workflow-builder-runtime.js

@@ -0,0 +1,137 @@
+import { WeftError } from "../weft-error.js";
+import { clonePlain } from "./clone-plain.js";
+import { deepFreeze } from "./deep-freeze.js";
+import { validateWorkflowOrActivityName } from "./name-grammar.js";
+
+export class WorkflowBuilderError extends WeftError {
+  constructor(message) {
+    super("WorkflowBuilderError", message);
+  }
+}
+
+export class WorkflowBuilderImpl {
+  #options;
+  #called = {
+    activities: !1,
+    signals: !1,
+    updates: !1,
+    queries: !1,
+    searchAttributes: !1
+  };
+  #executed = !1;
+  #activities = {};
+  #signals = {};
+  #updates = {};
+  #queries = {};
+  #searchAttributes = {};
+  constructor(options) {
+    this.#options = options;
+  }
+  #assertOpen(method) {
+    if (this.#executed)
+      throw new WorkflowBuilderError(`workflow("${this.#options.name}"): .${method}() called after .execute() \u2014 the builder is sealed once .execute() has run`);
+  }
+  #markCalled(method) {
+    if (this.#called[method])
+      throw new WorkflowBuilderError(`workflow("${this.#options.name}"): .${method}() can only be called once before .execute()`);
+    this.#called[method] = !0;
+  }
+  activities = (map) => {
+    this.#assertOpen("activities");
+    this.#markCalled("activities");
+    this.#activities = normalizeActivityMap(map);
+    return this;
+  };
+  signals = (map) => {
+    this.#assertOpen("signals");
+    this.#markCalled("signals");
+    this.#signals = { ...map };
+    return this;
+  };
+  updates = (map) => {
+    this.#assertOpen("updates");
+    this.#markCalled("updates");
+    this.#updates = { ...map };
+    return this;
+  };
+  queries = (map) => {
+    this.#assertOpen("queries");
+    this.#markCalled("queries");
+    this.#queries = { ...map };
+    return this;
+  };
+  searchAttributes = (schema) => {
+    this.#assertOpen("searchAttributes");
+    this.#markCalled("searchAttributes");
+    this.#searchAttributes = { ...schema };
+    return this;
+  };
+  execute = (fn) => {
+    this.#assertOpen("execute");
+    this.#executed = !0;
+    const frozenActivities = freezeRecord(this.#activities), frozenSignals = freezeRecord(this.#signals), frozenUpdates = freezeRecord(this.#updates), frozenQueries = freezeRecord(this.#queries), frozenSearchAttributes = deepFreeze(clonePlain(this.#searchAttributes)), handler = (context, input) => fn(context, input), built = {
+      name: this.#options.name,
+      handler,
+      activities: frozenActivities,
+      signals: frozenSignals,
+      updates: frozenUpdates,
+      queries: frozenQueries,
+      searchAttributes: frozenSearchAttributes,
+      ...this.#options.version !== void 0 ? { version: this.#options.version } : {},
+      ...this.#options.description !== void 0 ? { description: this.#options.description } : {},
+      ...this.#options.tags !== void 0 ? { tags: this.#options.tags } : {},
+      ...this.#options.retention !== void 0 ? { retention: this.#options.retention } : {},
+      ...this.#options.constraints !== void 0 ? { constraints: this.#options.constraints } : {},
+      ...this.#options.migrate !== void 0 ? { migrate: this.#options.migrate } : {},
+      ...this.#options.inputSchema !== void 0 ? { inputSchema: this.#options.inputSchema } : {},
+      ...this.#options.outputSchema !== void 0 ? { outputSchema: this.#options.outputSchema } : {}
+    };
+    return Object.freeze(built);
+  };
+}
+function freezeRecord(map) {
+  const out = {};
+  for (const key of Object.keys(map))
+    out[key] = deepFreeze(clonePlain(map[key]));
+  return Object.freeze(out);
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function hasExecuteProperty(value) {
+  if (value === null)
+    return !1;
+  const kind = typeof value;
+  if (kind !== "object" && kind !== "function")
+    return !1;
+  const record = value;
+  return "execute" in record && typeof record.execute === "function";
+}
+function normalizeActivityMap(map) {
+  const out = {};
+  for (const key of Object.keys(map)) {
+    validateWorkflowOrActivityName(key, "activity");
+    const entry = map[key];
+    if (hasExecuteProperty(entry)) {
+      const innerName = entry.name;
+      if (typeof innerName === "string" && innerName.length > 0 && innerName !== key)
+        throw new WorkflowBuilderError(`.activities(): key "${key}" disagrees with inner activity name "${innerName}". The outer key is canonical \u2014 remove the inner \`name\` field or align it with the key.`);
+      const { name: _ignored, execute, ...rest } = entry;
+      out[key] = {
+        ...rest,
+        name: key,
+        execute
+      };
+      continue;
+    }
+    if (isFunction(entry)) {
+      out[key] = {
+        name: key,
+        execute: entry
+      };
+      continue;
+    }
+    throw new WorkflowBuilderError(`.activities(): entry "${key}" must be a function, an activity() callable, or an object with an \`execute\` function`);
+  }
+  return out;
+}