@lostgradient/weft 0.2.0

package/dist/core/types/payload-size-policy.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Operator-configured upper bound on the serialized size of individual
+ * payloads. Large payloads — workflow input, signal payloads, activity results
+ * — are encoded into per-yield checkpoints and event-log entries, so an
+ * oversized value inflates every durable write and is re-deserialized on every
+ * replay. `maxBytes` caps the codec-boundary size (the codec-encoded byte
+ * length of the bare value, not the final on-disk record size) and rejects
+ * oversized payloads at admission, before any storage write. Pass via
+ * {@link EngineOptions.payloadSize}.
+ *
+ * Thresholds are operator config only — there are no baked-in defaults. Omit
+ * the policy (or set `maxBytes` to `0`/`null`) to disable the cap entirely;
+ * when disabled, no extra encode is performed, so the unconfigured path has
+ * zero added cost.
+ *
+ * The cap measures the codec-encoded byte length of the payload value before
+ * any storage-layer compression or record-envelope wrapping, and is an
+ * admission-time check: it rejects new oversized payloads but does not
+ * retroactively invalidate data already persisted under a larger (or disabled)
+ * limit, which remains replayable.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type PayloadSizePolicy } from '@lostgradient/weft';
+ *
+ * const payloadSize: PayloadSizePolicy = { maxBytes: 1_048_576 };
+ * const engine = new Engine({ payloadSize });
+ * void engine;
+ * ```
+ */
+export interface PayloadSizePolicy {
+    /**
+     * Maximum serialized (codec-encoded) byte length a single payload may have.
+     * A payload whose encoded size is exactly `maxBytes` is allowed; one byte
+     * larger is rejected with `PayloadSizeExceededError`. Must be a positive safe
+     * integer. `0`, `null`, omitted, or `undefined` disables the cap.
+     */
+    maxBytes?: number | null;
+}
+/**
+ * Payload-size policy after validation and normalisation. `maxBytes` is either
+ * a positive safe integer (cap active) or `null` (disabled). Used internally by
+ * the engine; callers configure via {@link PayloadSizePolicy}.
+ */
+export interface NormalizedPayloadSizePolicy {
+    maxBytes: number | null;
+}

package/dist/core/types/registry-type-helpers.d.ts

@@ -0,0 +1 @@
+export type UnknownNameWhenRegistryHasNoKnownNames<TName extends string, TKnownNames extends string> = [TKnownNames] extends [never] ? TName : never;

package/dist/core/types/retry-retention.d.ts

@@ -0,0 +1,163 @@
+/**
+ * A length of time accepted across the engine API.
+ *
+ * Either a number of milliseconds (`5000`) or a human-readable string
+ * (`'30s'`, `'5m'`, `'2h'`, `'1d'`). Supplies values for {@link RetryPolicy},
+ * `ctx.sleep()`, retention windows, schedule timing, and timeouts.
+ *
+ * @example Use a Duration in a retry policy
+ * ```ts
+ * import type { Duration, RetryPolicy } from '@lostgradient/weft';
+ *
+ * const initialBackoff: Duration = '500ms';
+ * const maxBackoff: Duration = '30s';
+ *
+ * const retry: RetryPolicy = {
+ *   maxAttempts: 5,
+ *   initialBackoff,
+ *   backoffMultiplier: 2,
+ *   maxBackoff,
+ * };
+ * void retry;
+ * ```
+ */
+export type Duration = number | string;
+/**
+ * How long the engine retains workflows in each terminal state before the
+ * retention sweep deletes them. All fields are optional {@link Duration}
+ * values (milliseconds or strings like `'7d'`). Pass via
+ * {@link EngineOptions.retention} for engine-wide defaults, or per-workflow
+ * via the builder's `retention` option (or `WorkflowDefinition.retention`).
+ *
+ * @example
+ * ```ts
+ * import { Engine, type RetentionPolicy } from '@lostgradient/weft';
+ *
+ * const retention: RetentionPolicy = {
+ *   completed: '7d',
+ *   failed: '30d',
+ *   cancelled: '3d',
+ * };
+ * const engine = new Engine({ retention });
+ * void engine;
+ * ```
+ */
+export interface RetentionPolicy {
+    completed?: Duration;
+    failed?: Duration;
+    cancelled?: Duration;
+    timedOut?: Duration;
+}
+/**
+ * Retention policy after {@link Duration} values have been normalised to
+ * milliseconds. Used internally by the engine's retention sweep; callers
+ * configure retention via {@link RetentionPolicy} which accepts human-readable
+ * strings like `'7d'`.
+ */
+export interface NormalizedRetentionPolicy {
+    completed?: number;
+    failed?: number;
+    cancelled?: number;
+    timedOut?: number;
+}
+/**
+ * Exponential-backoff retry policy for activities.
+ *
+ * Pass on `ActivityDefinition.retry` (set per-activity) or via the engine
+ * default policy. Backoff between attempts grows by `backoffMultiplier` and
+ * caps at `maxBackoff`. Errors whose `name` (or message) matches an entry in
+ * `nonRetryableErrors` skip the retry loop and fail fast.
+ *
+ * @example Configure a retry policy on an activity
+ * ```ts
+ * import { activity, type RetryPolicy } from '@lostgradient/weft';
+ *
+ * const retry: RetryPolicy = {
+ *   maxAttempts: 5,
+ *   initialBackoff: '500ms',
+ *   backoffMultiplier: 2,
+ *   maxBackoff: '30s',
+ *   nonRetryableErrors: ['ValidationError'],
+ * };
+ *
+ * const fetchUser = activity({
+ *   name: 'fetchUser',
+ *   retry,
+ *   execute: async (input: unknown) => {
+ *     return { id: input as string };
+ *   },
+ * });
+ * void fetchUser;
+ * ```
+ */
+export interface RetryPolicy {
+    maxAttempts: number;
+    initialBackoff: Duration;
+    backoffMultiplier: number;
+    maxBackoff: Duration;
+    nonRetryableErrors?: string[];
+}
+/**
+ * Retention policy entry for a specific workflow type, as reported by
+ * `engine.getRetentionOverview`. `source` indicates whether the policy
+ * came from the engine-level default, a per-workflow registration, or is
+ * absent entirely (`'none'`).
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, type WorkflowTypeRetentionPolicy } from '@lostgradient/weft';
+ *
+ * const engine = new Engine({ retention: { completed: '7d' } });
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ * const overview = await engine.getRetentionOverview();
+ * const policy: WorkflowTypeRetentionPolicy = overview.workflowTypes[0]!;
+ * console.log(policy.source); // 'engine'
+ * ```
+ */
+export interface WorkflowTypeRetentionPolicy {
+    type: string;
+    source: 'engine' | 'workflow' | 'none';
+    retention: NormalizedRetentionPolicy | null;
+}
+/**
+ * Summary of the engine's retention configuration, returned by
+ * `engine.getRetentionOverview()`. Lists the default retention policy,
+ * sweep schedule, and per-workflow-type overrides so operators can
+ * audit what cleanup behaviour is active.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type RetentionOverview } from '@lostgradient/weft';
+ *
+ * const engine = new Engine({ retention: { completed: '7d' } });
+ * const overview: RetentionOverview = await engine.getRetentionOverview();
+ * console.log(overview.sweepIntervalMs);
+ * console.log(overview.workflowTypes.length);
+ * ```
+ */
+export interface RetentionOverview {
+    defaultRetention: NormalizedRetentionPolicy | null;
+    sweepIntervalMs: number;
+    sweepBatchSize: number;
+    nextSweepAt: number | null;
+    workflowTypes: WorkflowTypeRetentionPolicy[];
+}
+/**
+ * Built-in retry policy applied to all activities that do not specify their
+ * own. Retries up to 3 times with 1 s initial backoff, doubling on each
+ * attempt and capping at 30 s. Override per-activity via
+ * {@link ActivityDefinition.retry} or per-call via {@link ActivityCallOptions.retry}.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_RETRY_POLICY, type RetryPolicy } from '@lostgradient/weft';
+ *
+ * // Extend the default policy with a custom non-retryable error list:
+ * const policy: RetryPolicy = {
+ *   ...DEFAULT_RETRY_POLICY,
+ *   nonRetryableErrors: ['ValidationError'],
+ * };
+ * void policy;
+ * ```
+ */
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;

package/dist/core/types/retry-retention.js

@@ -0,0 +1,6 @@
+export const DEFAULT_RETRY_POLICY = {
+  maxAttempts: 3,
+  initialBackoff: 1000,
+  backoffMultiplier: 2,
+  maxBackoff: 30000
+};

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

@@ -0,0 +1,170 @@
+import type { ReviewDecision as CompletedReviewDecision, ReviewRequest } from '../review/index.ts';
+/**
+ * Outcome of a human review step initiated by `ctx.waitForReview`. Pass as
+ * the `decision` field in {@link SubmitReviewOptions} when calling
+ * `engine.submitReview`.
+ */
+export type ReviewDecision = 'approved' | 'rejected' | 'needs-changes';
+/**
+ * Options for `engine.submitReview`. Supply the `decision`, the `reviewer`
+ * identifier, and optional `feedback`. For workflows with partial approval
+ * semantics, provide `sectionDecisions`. Pass `workflowId` when you know the
+ * target workflow ID to avoid a full storage scan.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type SubmitReviewOptions } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const options: SubmitReviewOptions = {
+ *   decision: 'approved',
+ *   reviewer: 'alice@example.com',
+ *   feedback: 'Looks good',
+ *   workflowId: 'wf-123',
+ * };
+ * // await engine.submitReview('review-key', options);
+ * void options;
+ * ```
+ */
+export interface SubmitReviewOptions {
+    decision: ReviewDecision;
+    reviewer: string;
+    feedback?: string;
+    /** Per-section decisions for partial approval workflows. */
+    sectionDecisions?: Record<string, 'approved' | 'rejected'>;
+    /** When provided, enables O(1) direct key lookup instead of scanning. */
+    workflowId?: string;
+}
+/**
+ * Status values returned by `engine.listReviews(filter?)`.
+ *
+ * Pending entries represent outstanding review requests; completed entries
+ * combine the original review metadata with the persisted reviewer decision.
+ *
+ * @example
+ * ```ts
+ * import type { ReviewStatus } from '@lostgradient/weft';
+ *
+ * const status: ReviewStatus = 'pending';
+ * void status;
+ * ```
+ */
+export type ReviewStatus = 'pending' | 'completed';
+/**
+ * Filter accepted by `engine.listReviews(filter?)` and the `/v1/reviews`
+ * transport surfaces.
+ *
+ * Omitting `status` preserves the legacy pending-only behavior.
+ *
+ * @example
+ * ```ts
+ * import type { ReviewListFilter } from '@lostgradient/weft';
+ *
+ * const filter: ReviewListFilter = {
+ *   status: 'completed',
+ *   workflowId: 'wf-123',
+ *   reviewType: 'security',
+ * };
+ * void filter;
+ * ```
+ */
+export interface ReviewListFilter {
+    status?: ReviewStatus;
+    workflowId?: string;
+    reviewType?: string;
+}
+/**
+ * Pending review entry returned by `engine.listReviews(filter?)`.
+ *
+ * Mirrors the durable review request plus a discriminating `status` field.
+ *
+ * @example
+ * ```ts
+ * import type { PendingReviewEntry } from '@lostgradient/weft';
+ *
+ * const entry: PendingReviewEntry = {
+ *   status: 'pending',
+ *   reviewId: 'review-1',
+ *   workflowId: 'wf-1',
+ *   artifact: { text: 'Please approve' },
+ *   reviewType: 'content',
+ *   reviewers: ['alice@example.com'],
+ *   allowPartial: false,
+ *   createdAt: Date.now(),
+ * };
+ * void entry;
+ * ```
+ */
+export interface PendingReviewEntry extends ReviewRequest {
+    status: 'pending';
+}
+/**
+ * Completed review entry returned by `engine.listReviews(filter?)`.
+ *
+ * Completed review records include the original request metadata plus the
+ * persisted reviewer decision.
+ *
+ * @example
+ * ```ts
+ * import type { CompletedReviewEntry } from '@lostgradient/weft';
+ *
+ * const entry: CompletedReviewEntry = {
+ *   status: 'completed',
+ *   reviewId: 'review-1',
+ *   workflowId: 'wf-1',
+ *   artifact: { text: 'Please approve' },
+ *   reviewType: 'content',
+ *   reviewers: ['alice@example.com'],
+ *   allowPartial: false,
+ *   createdAt: Date.now() - 5_000,
+ *   decision: 'approved',
+ *   reviewer: 'alice@example.com',
+ *   timestamp: Date.now(),
+ * };
+ * void entry;
+ * ```
+ */
+export interface CompletedReviewEntry extends CompletedReviewDecision {
+    status: 'completed';
+    workflowId: string;
+    artifact: unknown;
+    reviewType: string;
+    reviewers: string[];
+    allowPartial: boolean;
+    timeout?: number;
+    webhookUrl?: string;
+    createdAt: number;
+}
+/**
+ * Discriminated union returned by `engine.listReviews(filter?)`.
+ *
+ * Use `status` to branch between pending request metadata and completed
+ * decision metadata.
+ *
+ * @example
+ * ```ts
+ * import type { ReviewListEntry } from '@lostgradient/weft';
+ *
+ * function summarize(entry: ReviewListEntry): string {
+ *   return entry.status === 'completed'
+ *     ? `${entry.reviewType}: ${entry.decision}`
+ *     : `${entry.reviewType}: pending`;
+ * }
+ * void summarize;
+ * ```
+ */
+export type ReviewListEntry = PendingReviewEntry | CompletedReviewEntry;
+/**
+ * Result of a coordinated update sent via `engine.submitCoordinatedUpdate`.
+ * Contains the `updateId` and either the resolved `result` or an `error`
+ * string if the workflow handler threw.
+ * Exactly one of `result` or `error` is populated for a settled update:
+ * `result` on handler success, `error` (a stringified failure message) on
+ * handler throw. Both may be `undefined` on transport-level rejections from
+ * `HttpClient.submitCoordinatedUpdate`.
+ */
+export interface CoordinatedUpdateResult {
+    updateId: string;
+    result?: unknown;
+    error?: string;
+}

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

@@ -0,0 +1,176 @@
+import type { Duration } from './retry-retention.ts';
+import type { WorkflowDefinition } from './workflow-function.ts';
+/**
+ * Lifecycle state of a recurring schedule managed by {@link Engine.schedule}.
+ * `'active'` fires on cron cadence; `'paused'` skips upcoming runs without
+ * deleting the schedule; `'cancelled'` is the terminal removed state.
+ */
+export type ScheduleStatus = 'active' | 'paused' | 'cancelled';
+/**
+ * Behaviour when a scheduled cron tick fires while a previous run is still
+ * active. `'skip'` drops the new run; `'queue'` buffers it; `'cancel-running'`
+ * cancels the active workflow and starts fresh; `'allow'` starts both
+ * concurrently. Pass via {@link ScheduleOptions.overlap}.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, type ScheduleOverlapPolicy } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'hourly' }).execute(async function* () { return 'done'; }));
+ * const policy: ScheduleOverlapPolicy = 'skip';
+ * await engine.schedule('hourly', null, '0 * * * *', { overlap: policy });
+ * ```
+ */
+export type ScheduleOverlapPolicy = 'skip' | 'queue' | 'cancel-running' | 'allow';
+/**
+ * Recurrence specification for a schedule. A schedule fires either on a cron
+ * cadence (`{ cron: '0 9 * * *' }`) or at a fixed interval
+ * (`{ every: '1h' }`). Exactly one of `cron` or `every` must be supplied.
+ *
+ * Interval schedules are anchored at the schedule's creation time and fire one
+ * `every` period later, then every period after that. They reuse the same
+ * overlap and backfill machinery as cron schedules.
+ *
+ * @example
+ * ```ts
+ * import type { ScheduleSpec } from '@lostgradient/weft';
+ *
+ * const cronSpec: ScheduleSpec = { cron: '0 9 * * *' };
+ * const intervalSpec: ScheduleSpec = { every: '1h' };
+ * void [cronSpec, intervalSpec];
+ * ```
+ */
+export type ScheduleSpec = {
+    cron: string;
+    every?: never;
+} | {
+    every: Duration;
+    cron?: never;
+};
+/**
+ * Options accepted by {@link Engine.schedule}. `id` assigns a deterministic
+ * schedule identifier; `overlap` controls what happens when a tick fires while a
+ * previous run is still active; `backfill` triggers immediate runs for any ticks
+ * that were missed since the schedule was created.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, type ScheduleOptions } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'report' }).execute(async function* () { return 'ok'; }));
+ * const options: ScheduleOptions = { id: 'daily-report', overlap: 'skip', backfill: false };
+ * const handle = await engine.schedule('report', null, '0 9 * * *', options);
+ * void handle;
+ * ```
+ */
+export interface ScheduleOptions {
+    id?: string;
+    overlap?: ScheduleOverlapPolicy;
+    backfill?: boolean;
+}
+/**
+ * Declarative recurring schedule definition returned by {@link schedule}. Supply
+ * exactly one of `cron` (cron cadence) or `every` (fixed interval).
+ *
+ * @example
+ * ```ts
+ * import { schedule, type ScheduleDefinition } from '@lostgradient/weft';
+ *
+ * const dailyReport: ScheduleDefinition<{ day: string }> = schedule({
+ *   workflow: 'report',
+ *   cron: '0 9 * * *',
+ *   input: { day: 'today' },
+ *   overlapPolicy: 'skip',
+ * });
+ *
+ * const heartbeat: ScheduleDefinition<null> = schedule({
+ *   workflow: 'heartbeat',
+ *   every: '30s',
+ *   input: null,
+ * });
+ * void heartbeat;
+ * ```
+ */
+export type ScheduleDefinition<TInput = unknown> = ScheduleSpec & {
+    workflow: string | WorkflowDefinition<TInput>;
+    input: TInput;
+    id?: string;
+    overlapPolicy?: ScheduleOverlapPolicy;
+    backfill?: boolean;
+};
+/**
+ * Create a recurring schedule definition for `engine.schedule(definition)`.
+ *
+ * @example
+ * ```ts
+ * import { schedule } from '@lostgradient/weft';
+ *
+ * const definition = schedule({ workflow: 'report', cron: '0 9 * * *', input: null });
+ * ```
+ */
+export declare function schedule<TInput>(definition: ScheduleDefinition<TInput>): ScheduleDefinition<TInput>;
+/**
+ * Full persisted state of a recurring schedule. Returned by `engine.getSchedule(id)`.
+ * Use {@link ScheduleSummary} (returned by list operations and `engine.getSchedule()`)
+ * for the lightweight variant — it omits `input` to keep payloads small.
+ */
+export interface ScheduleState {
+    id: string;
+    workflowType: string;
+    input: unknown;
+    /**
+     * Cron expression driving the cadence for cron-based schedules. Present when
+     * `intervalMs` is absent; the two are mutually exclusive.
+     */
+    cronExpression?: string;
+    /**
+     * Fixed interval in milliseconds for interval-based schedules. Occurrences are
+     * anchored at `createdAt` and fire one interval later, then every interval
+     * after that. Present when `cronExpression` is absent.
+     */
+    intervalMs?: number;
+    status: ScheduleStatus;
+    overlap: ScheduleOverlapPolicy;
+    backfill: boolean;
+    createdAt: number;
+    updatedAt: number;
+    lastFireAt?: number;
+    nextFireAt: number | null;
+    currentWorkflowId?: string;
+    queuedRuns: number;
+}
+/**
+ * Lightweight summary of a recurring schedule returned by list operations.
+ * Contains cron expression, status, timing metadata, and the ID of the
+ * currently running workflow (if any). For the full record including the
+ * `input`, use {@link ScheduleState}.
+ */
+export interface ScheduleSummary {
+    id: string;
+    workflowType: string;
+    /** Cron expression for cron-based schedules; absent for interval schedules. */
+    cronExpression?: string;
+    /** Interval period in milliseconds for interval-based schedules; absent for cron schedules. */
+    intervalMs?: number;
+    status: ScheduleStatus;
+    overlap: ScheduleOverlapPolicy;
+    backfill: boolean;
+    createdAt: number;
+    updatedAt: number;
+    lastFireAt?: number;
+    nextFireAt: number | null;
+    currentWorkflowId?: string;
+    queuedRuns: number;
+}
+/**
+ * Filter criteria for `engine.listSchedules`. All fields are optional.
+ * `status` accepts one or more values; `limit` and `offset` control pagination.
+ */
+export interface ScheduleFilter {
+    status?: ScheduleStatus | ScheduleStatus[];
+    workflowType?: string;
+    limit?: number;
+    offset?: number;
+}

package/dist/core/types/schedules.js

@@ -0,0 +1,3 @@
+export function schedule(definition) {
+  return definition;
+}