@lostgradient/weft 0.2.0

package/dist/core/types/deep-freeze.js

@@ -0,0 +1,31 @@
+function shouldRecurse(value) {
+  if (value === null || typeof value !== "object")
+    return !1;
+  if (Array.isArray(value))
+    return !0;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function freezeChildren(value, seen) {
+  const entries = Array.isArray(value) ? value : Object.values(value);
+  for (const child of entries)
+    if (child !== null && typeof child === "object")
+      freezeWithSeen(child, seen);
+}
+function freezeWithSeen(value, seen) {
+  if (value === null || typeof value !== "object")
+    return value;
+  const objectValue = value;
+  if (seen.has(objectValue))
+    return value;
+  seen.add(objectValue);
+  if (Object.isFrozen(value))
+    return value;
+  if (shouldRecurse(value))
+    freezeChildren(objectValue, seen);
+  Object.freeze(value);
+  return value;
+}
+export function deepFreeze(value) {
+  return freezeWithSeen(value, new WeakSet);
+}

package/dist/core/types/definition-schema-to-json.d.ts

@@ -0,0 +1,41 @@
+import type { DefinitionSchema } from './definition-schema.ts';
+/**
+ * Direction parameter for {@link definitionSchemaToJsonSchema}. `"input"`
+ * produces the JSON Schema describing the validator's accepted input;
+ * `"output"` produces the schema describing the validated value.
+ *
+ * @example
+ * ```ts
+ * import type { DefinitionSchemaDirection } from '@lostgradient/weft';
+ *
+ * const direction: DefinitionSchemaDirection = 'input';
+ * void direction;
+ * ```
+ */
+export type DefinitionSchemaDirection = 'input' | 'output';
+/**
+ * Convert a {@link DefinitionSchema} to a JSON Schema fragment. Dispatch
+ * order:
+ *
+ * 1. **Built-in vendor adapters first** — Zod (`vendor === 'zod'`) and Valibot
+ *    (`vendor === 'valibot'`). This wins even when the schema also exposes a
+ *    `~standard.jsonSchema` converter, because libraries like Zod 4 ship a
+ *    structural converter that does not honor the project's
+ *    `unrepresentable: 'any'` option; deferring to the vendor adapter keeps
+ *    generated artifacts stable.
+ * 2. **Structural `~standard.jsonSchema.input` / `.output`** — used for
+ *    custom or third-party schemas without a built-in adapter.
+ * 3. **Otherwise throws** — no built-in adapter and no structural converter.
+ *
+ * @example
+ * ```ts
+ * import { definitionSchemaToJsonSchema } from '@lostgradient/weft';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({ email: z.string() });
+ * const jsonSchema = definitionSchemaToJsonSchema(schema);
+ * void jsonSchema;
+ * ```
+ */
+export declare function definitionSchemaToJsonSchema(schema: DefinitionSchema, direction?: DefinitionSchemaDirection): Record<string, unknown>;
+export declare function loadValibotConverter(requireModule?: (specifier: string) => unknown): (schema: unknown, options?: unknown) => unknown;

package/dist/core/types/definition-schema-to-json.js

@@ -0,0 +1,56 @@
+import { createRequire } from "node:module";
+import { z } from "zod";
+let cachedValibotConverter;
+export function definitionSchemaToJsonSchema(schema, direction = "input") {
+  const standard = schema["~standard"], vendor = standard.vendor;
+  if (vendor === "zod")
+    return convertZod(schema);
+  if (vendor === "valibot")
+    return convertValibot(schema);
+  const structuralConverter = standard.jsonSchema;
+  if (isStructuralConverter(structuralConverter)) {
+    const fn = structuralConverter[direction];
+    if (typeof fn === "function")
+      return stripDialect(requirePlainObject(fn({ target: defaultTarget }), `${vendor} structural converter`));
+    throw Error(`definitionSchemaToJsonSchema: schema "${vendor}" provides \`~standard.jsonSchema\` but no \`${direction}\` converter. Attach both \`input\` and \`output\` converters or convert in only one direction.`);
+  }
+  throw Error(`definitionSchemaToJsonSchema: no built-in adapter for vendor "${vendor}". Attach a \`~standard.jsonSchema\` converter to the schema, or use Zod or Valibot.`);
+}
+function isStructuralConverter(value) {
+  return value !== null && typeof value === "object";
+}
+const defaultTarget = "draft-2020-12";
+function convertZod(schema) {
+  const result = z.toJSONSchema(schema, { unrepresentable: "any" });
+  return stripDialect(requirePlainObject(result, "zod"));
+}
+function convertValibot(schema) {
+  const result = loadValibotConverter()(schema);
+  return stripDialect(requirePlainObject(result, "valibot"));
+}
+export function loadValibotConverter(requireModule) {
+  const shouldUseCache = requireModule === void 0, resolver = requireModule ?? createRequire(import.meta.url);
+  if (shouldUseCache && cachedValibotConverter !== void 0)
+    return cachedValibotConverter;
+  let valibotModule;
+  try {
+    valibotModule = resolver("@valibot/to-json-schema");
+  } catch (error) {
+    throw Error(`definitionSchemaToJsonSchema: \`@valibot/to-json-schema\` is not installed. Install it to convert Valibot schemas to JSON Schema, or attach a \`~standard.jsonSchema\` converter to your schema. Resolver error: ${String(error)}.`, { cause: error });
+  }
+  if (typeof valibotModule.toJsonSchema !== "function")
+    throw Error("definitionSchemaToJsonSchema: the installed `@valibot/to-json-schema` does not export `toJsonSchema`.");
+  return shouldUseCache ? cachedValibotConverter = valibotModule.toJsonSchema : valibotModule.toJsonSchema;
+}
+function stripDialect(object) {
+  if (!("$schema" in object))
+    return object;
+  const result = { ...object };
+  delete result.$schema;
+  return result;
+}
+function requirePlainObject(value, vendor) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value))
+    return value;
+  throw Error(`definitionSchemaToJsonSchema: ${vendor} converter returned a non-object (${typeof value}). Expected a JSON Schema object.`);
+}

package/dist/core/types/definition-schema.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Metadata stored under `~standard` by Standard Schema-compatible libraries.
+ *
+ * @example
+ * ```ts
+ * import type { StandardTypedV1Properties } from '@lostgradient/weft/json-schema';
+ *
+ * const properties: StandardTypedV1Properties = { version: 1, vendor: 'example' };
+ * void properties;
+ * ```
+ */
+export interface StandardTypedV1Properties<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly types?: StandardTypedV1Types<Input, Output> | undefined;
+}
+/**
+ * Compile-time input and output markers used by Standard Schema.
+ *
+ * @example
+ * ```ts
+ * import type { StandardTypedV1Types } from '@lostgradient/weft/json-schema';
+ *
+ * const types: StandardTypedV1Types<string, number> = {
+ *   input: '',
+ *   output: 0,
+ * };
+ * void types;
+ * ```
+ */
+export interface StandardTypedV1Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+}
+/**
+ * Standard Schema v1 validator metadata stored under `~standard`.
+ *
+ * @example
+ * ```ts
+ * import type { StandardSchemaV1Properties } from '@lostgradient/weft/json-schema';
+ *
+ * const properties: StandardSchemaV1Properties<unknown, string> = {
+ *   version: 1,
+ *   vendor: 'example',
+ *   validate: (value) =>
+ *     typeof value === 'string' ? { value } : { issues: [{ message: 'Expected a string.' }] },
+ * };
+ * void properties;
+ * ```
+ */
+export interface StandardSchemaV1Properties<Input = unknown, Output = Input> extends StandardTypedV1Properties<Input, Output> {
+    readonly validate: (value: unknown, options?: StandardSchemaV1Options) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+}
+/**
+ * Result returned by a Standard Schema v1 validator.
+ *
+ * @example
+ * ```ts
+ * import type { StandardSchemaV1Result } from '@lostgradient/weft/json-schema';
+ *
+ * const result: StandardSchemaV1Result<string> = { value: 'ok' };
+ * void result;
+ * ```
+ */
+export type StandardSchemaV1Result<Output> = StandardSchemaV1SuccessResult<Output> | StandardSchemaV1FailureResult;
+/**
+ * Successful Standard Schema v1 validation result.
+ *
+ * @example
+ * ```ts
+ * import type { StandardSchemaV1SuccessResult } from '@lostgradient/weft/json-schema';
+ *
+ * const result: StandardSchemaV1SuccessResult<string> = { value: 'ok' };
+ * void result;
+ * ```
+ */
+export interface StandardSchemaV1SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+}
+/**
+ * Failed Standard Schema v1 validation result.
+ *
+ * @example
+ * ```ts
+ * import type { StandardSchemaV1FailureResult } from '@lostgradient/weft/json-schema';
+ *
+ * const result: StandardSchemaV1FailureResult = {
+ *   issues: [{ message: 'Expected a string.' }],
+ * };
+ * void result;
+ * ```
+ */
+export interface StandardSchemaV1FailureResult {
+    readonly issues: ReadonlyArray<StandardSchemaV1Issue>;
+}
+/**
+ * Single validation issue reported by a Standard Schema v1 validator.
+ *
+ * @example
+ * ```ts
+ * import type { StandardSchemaV1Issue } from '@lostgradient/weft/json-schema';
+ *
+ * const issue: StandardSchemaV1Issue = { message: 'Expected a string.' };
+ * void issue;
+ * ```
+ */
+export interface StandardSchemaV1Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | StandardSchemaV1PathSegment> | undefined;
+}
+/**
+ * Structured path segment in a Standard Schema v1 issue path.
+ *
+ * @example
+ * ```ts
+ * import type { StandardSchemaV1PathSegment } from '@lostgradient/weft/json-schema';
+ *
+ * const segment: StandardSchemaV1PathSegment = { key: 'email' };
+ * void segment;
+ * ```
+ */
+export interface StandardSchemaV1PathSegment {
+    readonly key: PropertyKey;
+}
+/**
+ * Options passed to a Standard Schema v1 validator.
+ *
+ * @example
+ * ```ts
+ * import type { StandardSchemaV1Options } from '@lostgradient/weft/json-schema';
+ *
+ * const options: StandardSchemaV1Options = { libraryOptions: { abortEarly: true } };
+ * void options;
+ * ```
+ */
+export interface StandardSchemaV1Options {
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+}
+/**
+ * Standard JSON Schema v1 converter metadata stored under `~standard`.
+ *
+ * @example
+ * ```ts
+ * import type { StandardJSONSchemaV1Properties } from '@lostgradient/weft/json-schema';
+ *
+ * const properties: StandardJSONSchemaV1Properties = {
+ *   version: 1,
+ *   vendor: 'example',
+ *   jsonSchema: {
+ *     input: () => ({ type: 'object' }),
+ *     output: () => ({ type: 'object' }),
+ *   },
+ * };
+ * void properties;
+ * ```
+ */
+export interface StandardJSONSchemaV1Properties<Input = unknown, Output = Input> extends StandardTypedV1Properties<Input, Output> {
+    readonly jsonSchema: StandardJSONSchemaV1Converter;
+}
+/**
+ * Input and output JSON Schema converter functions.
+ *
+ * @example
+ * ```ts
+ * import type { StandardJSONSchemaV1Converter } from '@lostgradient/weft/json-schema';
+ *
+ * const converter: StandardJSONSchemaV1Converter = {
+ *   input: () => ({ type: 'object' }),
+ *   output: () => ({ type: 'object' }),
+ * };
+ * void converter;
+ * ```
+ */
+export interface StandardJSONSchemaV1Converter {
+    readonly input: (options: StandardJSONSchemaV1Options) => Record<string, unknown>;
+    readonly output: (options: StandardJSONSchemaV1Options) => Record<string, unknown>;
+}
+/**
+ * JSON Schema target dialect requested from a Standard JSON Schema converter.
+ *
+ * @example
+ * ```ts
+ * import type { StandardJSONSchemaV1Target } from '@lostgradient/weft/json-schema';
+ *
+ * const target: StandardJSONSchemaV1Target = 'draft-2020-12';
+ * void target;
+ * ```
+ */
+export type StandardJSONSchemaV1Target = 'draft-2020-12' | 'draft-07' | 'openapi-3.0' | ({} & string);
+/**
+ * Options passed to Standard JSON Schema converter functions.
+ *
+ * @example
+ * ```ts
+ * import type { StandardJSONSchemaV1Options } from '@lostgradient/weft/json-schema';
+ *
+ * const options: StandardJSONSchemaV1Options = { target: 'draft-2020-12' };
+ * void options;
+ * ```
+ */
+export interface StandardJSONSchemaV1Options {
+    readonly target: StandardJSONSchemaV1Target;
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+}
+/**
+ * Base type metadata shared by the Standard Schema family.
+ *
+ * Weft copies the small structural interfaces it consumes instead of taking a
+ * runtime dependency on [`@standard-schema/spec`](https://www.npmjs.com/package/@standard-schema/spec).
+ * The runtime contract is the `~standard` property; libraries such as
+ * [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and
+ * [ArkType](https://arktype.io/) can satisfy it structurally.
+ *
+ * @example
+ * ```ts
+ * import type { StandardTypedV1 } from '@lostgradient/weft/json-schema';
+ *
+ * const typedMetadata = {
+ *   '~standard': { version: 1, vendor: 'example' },
+ * } satisfies StandardTypedV1<unknown, unknown>;
+ *
+ * void typedMetadata;
+ * ```
+ */
+export interface StandardTypedV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardTypedV1Properties<Input, Output>;
+}
+/**
+ * Standard Schema v1 validation surface.
+ *
+ * @example
+ * ```ts
+ * import type { StandardSchemaV1 } from '@lostgradient/weft/json-schema';
+ *
+ * const stringSchema = {
+ *   '~standard': {
+ *     version: 1,
+ *     vendor: 'example',
+ *     validate(value: unknown) {
+ *       return typeof value === 'string'
+ *         ? { value }
+ *         : { issues: [{ message: 'Expected a string.' }] };
+ *     },
+ *   },
+ * } satisfies StandardSchemaV1<unknown, string>;
+ *
+ * void stringSchema;
+ * ```
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1Properties<Input, Output>;
+}
+/**
+ * Standard JSON Schema v1 conversion surface.
+ *
+ * @example
+ * ```ts
+ * import type { StandardJSONSchemaV1 } from '@lostgradient/weft/json-schema';
+ *
+ * const jsonSchemaMetadata = {
+ *   '~standard': {
+ *     version: 1,
+ *     vendor: 'example',
+ *     jsonSchema: {
+ *       input: () => ({ type: 'object' }),
+ *       output: () => ({ type: 'object' }),
+ *     },
+ *   },
+ * } satisfies StandardJSONSchemaV1<Record<string, unknown>>;
+ *
+ * void jsonSchemaMetadata;
+ * ```
+ */
+export interface StandardJSONSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardJSONSchemaV1Properties<Input, Output>;
+}
+/**
+ * Schema metadata accepted by workflow and activity definitions.
+ *
+ * Validation and JSON Schema conversion are separate capabilities. A schema may
+ * provide validation only, JSON Schema conversion only, or both. Core workflow
+ * and activity registration validates this metadata shape for introspection;
+ * adapters must opt in explicitly before using it for runtime input or output
+ * validation.
+ *
+ * @example
+ * ```ts
+ * import type { DefinitionSchema } from '@lostgradient/weft/json-schema';
+ *
+ * function acceptsDefinitionSchema(schema: DefinitionSchema): DefinitionSchema {
+ *   return schema;
+ * }
+ *
+ * void acceptsDefinitionSchema;
+ * ```
+ */
+export type DefinitionSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> | StandardJSONSchemaV1<Input, Output>;
+/**
+ * Extract the schema's *input* type — what the validator accepts before any
+ * transform runs. For a schema like `z.string().transform(s => s.length)`,
+ * `InferSchemaInput` is `string`. Helpers in the codebase use this when they
+ * want the wire-side / pre-validation type; for handler-side / post-validation
+ * payloads, see {@link InferSchemaOutput}. When a schema omits
+ * `~standard.types`, inference usually widens to `unknown`, so typed markers
+ * are required to preserve a concrete input type.
+ *
+ * @example
+ * ```ts
+ * import type { InferSchemaInput } from '@lostgradient/weft/json-schema';
+ * import { z } from 'zod';
+ *
+ * const schema = z.string().transform((s) => s.length);
+ * type Input = InferSchemaInput<typeof schema>; // string
+ * const value: Input = 'hello';
+ * void value;
+ * ```
+ */
+export type InferSchemaInput<TSchema> = TSchema extends StandardTypedV1<infer Input, unknown> ? Input : never;
+/**
+ * Extract the schema's *output* type — what the validator produces after any
+ * transform runs. For a schema like `z.string().transform(s => s.length)`,
+ * `InferSchemaOutput` is `number`. The definition helpers use this for
+ * handler-side payload types: handlers see the validated, parsed value. When a
+ * schema omits `~standard.types`, inference usually widens to `unknown`, so
+ * typed markers are required to preserve a concrete output type.
+ *
+ * @example
+ * ```ts
+ * import type { InferSchemaOutput } from '@lostgradient/weft/json-schema';
+ * import { z } from 'zod';
+ *
+ * const schema = z.string().transform((s) => s.length);
+ * type Output = InferSchemaOutput<typeof schema>; // number
+ * const value: Output = 5;
+ * void value;
+ * ```
+ */
+export type InferSchemaOutput<TSchema> = TSchema extends StandardTypedV1<unknown, infer Output> ? Output : never;
+export declare function isDefinitionSchema(value: unknown): value is DefinitionSchema;
+export declare function validateDefinitionSchemaMetadata(value: unknown, fieldName: string): DefinitionSchema;

package/dist/core/types/definition-schema.js

@@ -0,0 +1,45 @@
+export function isDefinitionSchema(value) {
+  const standardRecord = getStandardMetadataRecord(value);
+  if (standardRecord === void 0)
+    return !1;
+  if (typeof standardRecord.validate === "function")
+    return !0;
+  return isStandardJsonSchemaConverter(standardRecord.jsonSchema);
+}
+export function validateDefinitionSchemaMetadata(value, fieldName) {
+  if (isDefinitionSchema(value))
+    return value;
+  throw TypeError(`${fieldName} must be Standard Schema-compatible definition metadata. Pass a Zod, Valibot, ArkType (or any Standard Schema v1) validator, or attach a \`~standard.jsonSchema\` converter directly. Received: ${describeReceivedValue(value)}.`);
+}
+function describeReceivedValue(value) {
+  if (value === null)
+    return "null";
+  if (value === void 0)
+    return "undefined";
+  if (Array.isArray(value))
+    return "array";
+  if (typeof value !== "object")
+    return typeof value;
+  const keys = Object.keys(value);
+  if (keys.length === 0)
+    return "an empty object";
+  return `an object with keys [${keys.slice(0, 5).join(", ")}${keys.length > 5 ? ", \u2026" : ""}]`;
+}
+function getStandardMetadataRecord(value) {
+  if (value === null || typeof value !== "object")
+    return;
+  const standard = value["~standard"];
+  if (standard === null || typeof standard !== "object")
+    return;
+  const standardRecord = standard;
+  if (standardRecord.version !== 1)
+    return;
+  if (typeof standardRecord.vendor !== "string" || standardRecord.vendor.length === 0)
+    return;
+  return standardRecord;
+}
+function isStandardJsonSchemaConverter(jsonSchema) {
+  if (jsonSchema === null || typeof jsonSchema !== "object")
+    return !1;
+  return typeof jsonSchema.input === "function" && typeof jsonSchema.output === "function";
+}

package/dist/core/types/history-policy.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Operator-configured upper bound on workflow history. Activation rehydrates a
+ * workflow by replaying its event log, so cost is O(history); an unbounded log
+ * (e.g. a runaway infinite-yield loop) can stall the shared single-process
+ * engine for every workflow. `maxEvents` is a safety backstop: once a
+ * workflow's durable event-log record count would exceed it, the engine forces
+ * the workflow to a terminal `timed-out` state. Pass via
+ * {@link EngineOptions.history}.
+ *
+ * Thresholds are operator config only — there are no baked-in defaults. Omit
+ * the policy (or `maxEvents`) to disable the circuit breaker.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type HistoryPolicy } from '@lostgradient/weft';
+ *
+ * const history: HistoryPolicy = { maxEvents: 100_000 };
+ * const engine = new Engine({ history });
+ * void engine;
+ * ```
+ */
+export interface HistoryPolicy {
+    /**
+     * Maximum number of event-log records a workflow may accumulate. Exactly
+     * `maxEvents` records are allowed; the record that would push the count to
+     * `maxEvents + 1` trips the circuit breaker and the workflow is forced to
+     * `timed-out`. Must be a positive safe integer. `0`, omitted, or `undefined`
+     * disables enforcement.
+     *
+     * `maxEvents` counts the **lifetime** event-log sequence (`head.sequence + 1`),
+     * which `retentionWindow` compaction never resets — compaction reclaims storage
+     * but does not make a workflow semantically younger, so the circuit breaker
+     * still fires on total lifetime events.
+     */
+    maxEvents?: number;
+    /**
+     * Event-log compaction window: keep **at most** the `retentionWindow` most
+     * recent event-log records (measured against the head sequence) and truncate
+     * older records behind a confirmed checkpoint to reclaim storage. The canonical
+     * checkpoint already holds the compacted state, so truncation never affects
+     * resume. `retentionWindow: 1` keeps only the head record. Must be a positive
+     * safe integer. `0`, omitted, or `undefined` disables compaction.
+     *
+     * "At most", not "exactly": the compaction watermark only ever advances forward,
+     * so raising `retentionWindow` after compaction has run does not restore
+     * already-truncated history. Distinct from {@link maxEvents}: that is a
+     * circuit-breaker backstop on lifetime count; this is storage reclamation. They
+     * share validation mechanics only.
+     */
+    retentionWindow?: number;
+}
+/**
+ * History policy after validation and normalisation. `maxEvents` is either a
+ * positive safe integer (enforcement active) or `null` (disabled). Used
+ * internally by the engine; callers configure via {@link HistoryPolicy}.
+ */
+export interface NormalizedHistoryPolicy {
+    maxEvents: number | null;
+    retentionWindow: number | null;
+}
+/**
+ * Terminal reason recorded on a workflow forced to `timed-out` by the history
+ * circuit breaker. Distinguishes circuit-breaker termination from an ordinary
+ * deadline timeout (which carries no reason). A single-member union today;
+ * widen as additional distinct termination reasons are introduced.
+ *
+ * @example
+ * ```ts
+ * import { HISTORY_CIRCUIT_BREAKER_REASON, type TerminationReason } from '@lostgradient/weft';
+ *
+ * const reason: TerminationReason = HISTORY_CIRCUIT_BREAKER_REASON;
+ * void reason;
+ * ```
+ */
+export type TerminationReason = typeof HISTORY_CIRCUIT_BREAKER_REASON;
+/**
+ * Value written to `WorkflowState.terminationReason` and
+ * `WorkflowTimedOutEvent.reason` when the history circuit breaker fires. Compare
+ * against it to tell circuit-breaker termination apart from a deadline timeout.
+ *
+ * @example
+ * ```ts
+ * import { Engine, HISTORY_CIRCUIT_BREAKER_REASON } from '@lostgradient/weft';
+ *
+ * const engine = new Engine({ history: { maxEvents: 100_000 } });
+ * const state = await engine.get('some-workflow-id');
+ * if (state?.terminationReason === HISTORY_CIRCUIT_BREAKER_REASON) {
+ *   console.log('terminated by the history circuit breaker');
+ * }
+ * ```
+ */
+export declare const HISTORY_CIRCUIT_BREAKER_REASON = "history-circuit-breaker";

package/dist/core/types/history-policy.js

@@ -0,0 +1 @@
+export const HISTORY_CIRCUIT_BREAKER_REASON = "history-circuit-breaker";

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

@@ -0,0 +1,55 @@
+/**
+ * Opaque string identifier for a workflow instance. Generated automatically
+ * by the engine at start time, or supplied via {@link StartOptions.id}. Pass
+ * to {@link Engine.getHandle} or {@link Engine.get} to look up a running or
+ * completed workflow.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, type WorkflowId } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ *
+ * const handle = await engine.start('ping', null);
+ * const id: WorkflowId = handle.id;
+ * const state = await engine.get(id);
+ * console.log(state?.status); // 'completed'
+ * ```
+ */
+export type WorkflowId = string;
+export type OperationId = string;
+/**
+ * Classifies why a workflow failed. Populated automatically by the engine on
+ * failure so operators can query e.g. "all timeout failures in the last hour"
+ * via `engine.list({ attributes: [{ key: 'failureCategory', value: 'timeout' }] })`.
+ *
+ * - `'application'` — workflow or activity application code threw
+ * - `'timeout'` — execution exceeded a configured deadline
+ * - `'cancellation'` — cancellation or abort ended execution
+ * - `'resource'` — quota, memory, disk, or capacity limit was exceeded
+ * - `'system'` — engine, storage, or worker infrastructure fault
+ *
+ * @example
+ * ```ts
+ * import { Engine, type FailureCategory } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * // Query all workflows that failed due to a timeout:
+ * const results = await engine.list({
+ *   status: 'failed',
+ *   attributes: [{ key: 'failureCategory', value: 'timeout' as FailureCategory }],
+ * });
+ * void results;
+ * ```
+ */
+export type FailureCategory = 'application' | 'timeout' | 'cancellation' | 'resource' | 'system';
+/**
+ * Lifecycle states a workflow moves through, from registration to terminal
+ * state.
+ *
+ * Read this off `(await handle.state()).status` to learn whether a workflow
+ * is still running, finished cleanly, or failed. Pass it to `engine.list()`
+ * filters to scope queries by status.
+ */
+export type WorkflowStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'timed-out';