@lostgradient/weft 0.23.1 → 0.24.1

package/dist/core/registry-workflow-contract-draft.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Projects a converted {@link RegistryWorkflowEntry} into the
+ * `core/contract` {@link WorkflowContract} shape {@link buildRegistrySnapshot}
+ * feeds to `buildWorkflowRevisionManifest`.
+ *
+ * Split out of `core/registry-snapshot.ts` specifically to stay under the
+ * repository's implementation-file-size ceiling once WFT-6's workflow-scoped
+ * activity folding (`buildRegistrySnapshot` reading
+ * `Engine.listWorkflowActivityDefinitions`) was added there.
+ *
+ * @module core/registry-workflow-contract-draft
+ */
+import type { WorkflowActivityContract, WorkflowContract } from './contract/index.ts';
+import type { RegistryWorkflowEntry } from './registry-snapshot.ts';
+/**
+ * Project a converted {@link RegistryWorkflowEntry} (schemas already turned
+ * into JSON Schema by `buildWorkflowEntry`) into the `core/contract`
+ * {@link WorkflowContract} shape `buildWorkflowRevisionManifest` consumes.
+ * Deliberately does not re-run schema conversion — `entry`'s schemas are
+ * already `Record<string, unknown>` JSON Schema, structurally identical to
+ * what `WorkflowContract` expects, so re-converting through
+ * `buildWorkflowContract` (which expects raw `DefinitionSchema`) would
+ * double-convert and risk a different error shape for the same failure.
+ *
+ * `workflowScopedActivities`, when non-empty, becomes the draft's
+ * `activities` — the workflow's own `.activities({...})` registrations
+ * (`Engine.listWorkflowActivityDefinitions`), never the flat,
+ * workflow-independent `RegistrySnapshot.activities` catalog. Omitted
+ * (rather than `{}`) when empty, matching this module's "absent fields
+ * omitted" convention.
+ */
+export declare function toWorkflowContractDraft(workflowType: string, workflowVersion: string, entry: RegistryWorkflowEntry, workflowScopedActivities: Readonly<Record<string, WorkflowActivityContract>>): WorkflowContract;

package/dist/core/registry-workflow-contract-draft.js

@@ -0,0 +1,28 @@
+function applyDraftSchemas(draft, entry) {
+  if (entry.description !== void 0)
+    draft.description = entry.description;
+  if (entry.tags !== void 0 && entry.tags.length > 0)
+    draft.tags = entry.tags;
+  if (entry.inputSchema !== void 0)
+    draft.inputSchema = entry.inputSchema;
+  if (entry.outputSchema !== void 0)
+    draft.outputSchema = entry.outputSchema;
+}
+function applyDraftMessages(draft, entry) {
+  if (entry.signals !== void 0 && Object.keys(entry.signals).length > 0)
+    draft.signals = entry.signals;
+  if (entry.updates !== void 0 && Object.keys(entry.updates).length > 0)
+    draft.updates = entry.updates;
+  if (entry.queries !== void 0 && Object.keys(entry.queries).length > 0)
+    draft.queries = entry.queries;
+}
+export function toWorkflowContractDraft(workflowType, workflowVersion, entry, workflowScopedActivities) {
+  const draft = { name: workflowType, workflowVersion };
+  applyDraftSchemas(draft, entry);
+  applyDraftMessages(draft, entry);
+  if (entry.finalizer !== void 0)
+    draft.finalizer = entry.finalizer;
+  if (Object.keys(workflowScopedActivities).length > 0)
+    draft.activities = workflowScopedActivities;
+  return draft;
+}

package/dist/core/registry-workflow-manifest.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Build one registered workflow's {@link WorkflowRevisionManifest} — the
+ * per-workflow entry/message/scoped-activity conversion `buildRegistrySnapshot`
+ * (`registry-snapshot.ts`) folds into every manifest in a full snapshot, and
+ * that {@link buildWorkflowManifestForType} exposes standalone for a caller
+ * that wants one or a few workflows' manifests without reading, hashing, or
+ * being bounded by the rest of the engine's registrations.
+ *
+ * Split out of `registry-snapshot.ts` specifically so `buildWorkerManifestFromRegistry`
+ * (`worker/manifest/registry-contract-builder.ts`) can depend on
+ * {@link buildWorkflowManifestForType} without also inheriting
+ * `buildRegistrySnapshot`'s full-snapshot `RegistryWorkflowCountLimitError`
+ * aggregate check, or an *unrelated* registered workflow's own
+ * {@link RegistryManifestLimitError} — neither is the right contract for a
+ * caller that only ever looks up the handful of workflows it names.
+ *
+ * @module core/registry-workflow-manifest
+ */
+import type { ActivityMetadata } from './activity-registry.ts';
+import { type WorkflowRevisionManifest } from './contract/index.ts';
+import type { Engine } from './engine.ts';
+import type { RegisteredWorkflowDefinition } from './types/workflow-registry.ts';
+import { WeftError } from './weft-error.ts';
+/** Schema metadata reported for a statically registered workflow message. */
+export type RegistryMessageEntry = {
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+};
+/** Metadata reported per workflow in a registry snapshot. */
+export type RegistryWorkflowEntry = {
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    description?: string;
+    tags?: ReadonlyArray<string>;
+    signals?: Record<string, RegistryMessageEntry>;
+    updates?: Record<string, RegistryMessageEntry>;
+    queries?: Record<string, RegistryMessageEntry>;
+    /** Schema metadata for the workflow's definition-level finalizer activity, when registered. */
+    finalizer?: RegistryMessageEntry;
+};
+/**
+ * Thrown when a registered workflow's contract cannot be published as a
+ * {@link WorkflowRevisionManifest} because it exceeds one of the WFT-5
+ * hostile-input limits (`core/contract/limits.ts`) — an identifier over
+ * `MAX_CONTRACT_IDENTIFIER_BYTES`, too many signal/update/query/activity
+ * entries, a schema nested past `MAX_CONTRACT_SCHEMA_DEPTH`, or a
+ * normalized contract over `MAX_NORMALIZED_CONTRACT_BYTES`. Nothing in
+ * engine registration enforces those bounds (`name-grammar.ts` has no
+ * length cap; `description`/`tags`/`version`/schema depth are unbounded at
+ * registration time), so a registration the engine happily accepts can
+ * still fail here, at manifest-build time. Mirrors
+ * `RegistrySchemaConversionError`'s masked-500 handling in
+ * `server/operations/get-registry.ts`: the wire response stays a generic
+ * `500 / Internal server error`, and `workflowType` plus the underlying
+ * limit reason reach server-side logs only.
+ */
+export declare class RegistryManifestLimitError extends WeftError<'RegistryManifestLimitError'> {
+    readonly workflowType: string;
+    constructor(workflowType: string, cause: unknown);
+}
+/**
+ * Build one workflow definition's {@link WorkflowRevisionManifest} from its
+ * already-resolved scoped activity metadata, folding in its
+ * `.activities({...})`-scoped registrations (WFT-6). This is the shared
+ * normalization core both {@link buildOneWorkflowManifest} (the eager
+ * `engine.register()` drain path, which looks `activityDefinitions` up from
+ * the engine's registry) and the dynamic workflow-source loader path
+ * (WFT-13/14, `core/source/validate.ts`, which has no committed `Engine`
+ * registration to look up from) route through — so a workflow registered
+ * both eagerly and lazily from logically identical content always produces
+ * byte-identical manifests, never two independently-derived contracts that
+ * could disagree.
+ *
+ * Throws {@link RegistryManifestLimitError} if `definition`'s contract
+ * exceeds a WFT-5 hostile-input limit.
+ *
+ * @example
+ * ```ts
+ * import { Engine } from '@lostgradient/weft';
+ *
+ * declare const engine: Engine;
+ * const definition = engine.getWorkflowDefinition('checkout');
+ * void definition;
+ * ```
+ */
+export declare function buildWorkflowManifestFromDefinition(definition: RegisteredWorkflowDefinition, activityDefinitions: readonly ActivityMetadata[]): Promise<WorkflowRevisionManifest>;
+/**
+ * Build one registered workflow's {@link WorkflowRevisionManifest}, folding
+ * in its `.activities({...})`-scoped registrations (WFT-6). Shared by
+ * `buildRegistrySnapshot`'s per-workflow `Promise.all` and
+ * {@link buildWorkflowManifestForType}'s single-workflow lookup, so the two
+ * call paths can never disagree on what one workflow's manifest contains.
+ * A thin wrapper around {@link buildWorkflowManifestFromDefinition} that
+ * resolves `activityDefinitions` from `engine`'s own registry.
+ *
+ * Throws {@link RegistryManifestLimitError} if `definition`'s contract
+ * exceeds a WFT-5 hostile-input limit.
+ */
+export declare function buildOneWorkflowManifest(engine: Engine, definition: RegisteredWorkflowDefinition): Promise<WorkflowRevisionManifest>;
+/**
+ * Build a single registered workflow's {@link WorkflowRevisionManifest} —
+ * the scoped counterpart to `buildRegistrySnapshot` for a caller that wants
+ * one or a few workflows' manifests without reading, hashing, or being
+ * bounded by the rest of the engine's registrations.
+ * `buildWorkerManifestFromRegistry` (`worker/manifest/registry-contract-builder.ts`)
+ * is exactly that caller: it resolves only the workflows its own
+ * caller-declared `options.workflows` names, so neither
+ * `RegistryWorkflowCountLimitError` (an aggregate, whole-snapshot concern)
+ * nor an unrelated registration's own {@link RegistryManifestLimitError}
+ * should ever block it from producing an otherwise-valid,
+ * independently-bounded worker manifest for the workflows it actually
+ * asked for.
+ *
+ * Returns `undefined` if `workflowType` is not registered on `engine` — the
+ * caller decides how to report that (`buildWorkerManifestFromRegistry`
+ * throws `WorkerManifestBuildError`, naming the type).
+ *
+ * Throws a schema-conversion error if the registered schema fails JSON
+ * Schema conversion, or {@link RegistryManifestLimitError} if the contract
+ * exceeds a WFT-5 hostile-input limit.
+ */
+export declare function buildWorkflowManifestForType(engine: Engine, workflowType: string): Promise<WorkflowRevisionManifest | undefined>;

package/dist/core/registry-workflow-manifest.js

@@ -0,0 +1,92 @@
+import { compareCodepoint } from "./compare-codepoint.js";
+import {
+  buildWorkflowRevisionManifest
+} from "./contract/index.js";
+import { convertSchema } from "./registry-schema-conversion.js";
+import { toWorkflowContractDraft } from "./registry-workflow-contract-draft.js";
+import { WeftError } from "./weft-error.js";
+
+export class RegistryManifestLimitError extends WeftError {
+  workflowType;
+  constructor(workflowType, cause) {
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    super("RegistryManifestLimitError", `Registered workflow "${workflowType}" cannot be published to the registry: ${causeMessage}`, { cause });
+    this.workflowType = workflowType;
+  }
+}
+function buildWorkflowScopedActivityContracts(activityDefinitions, workflowType) {
+  const activities = Object.create(null), scoped = [...activityDefinitions].toSorted((a, b) => compareCodepoint(a.name, b.name));
+  for (const metadata of scoped) {
+    const entityName = `${workflowType}.activities.${metadata.name}`, contract = {};
+    if (metadata.inputSchema !== void 0)
+      contract.inputSchema = convertSchema("activity", entityName, "inputSchema", metadata.inputSchema);
+    if (metadata.outputSchema !== void 0)
+      contract.outputSchema = convertSchema("activity", entityName, "outputSchema", metadata.outputSchema);
+    activities[metadata.name] = contract;
+  }
+  return activities;
+}
+function buildWorkflowEntry(definition) {
+  const entry = {};
+  if (definition.inputSchema !== void 0)
+    entry.inputSchema = convertSchema("workflow", definition.type, "inputSchema", definition.inputSchema);
+  if (definition.outputSchema !== void 0)
+    entry.outputSchema = convertSchema("workflow", definition.type, "outputSchema", definition.outputSchema);
+  if (definition.description !== void 0)
+    entry.description = definition.description;
+  if (definition.tags.length > 0)
+    entry.tags = [...definition.tags];
+  addWorkflowMessageEntries(entry, definition);
+  addFinalizerEntry(entry, definition);
+  return entry;
+}
+function addFinalizerEntry(entry, definition) {
+  if (definition.finalizer === void 0)
+    return;
+  const entityName = `${definition.type}.finalizer`, finalizerEntry = {};
+  if (definition.finalizer.inputSchema !== void 0)
+    finalizerEntry.inputSchema = convertSchema("workflow", entityName, "inputSchema", definition.finalizer.inputSchema);
+  if (definition.finalizer.outputSchema !== void 0)
+    finalizerEntry.outputSchema = convertSchema("workflow", entityName, "outputSchema", definition.finalizer.outputSchema);
+  entry.finalizer = finalizerEntry;
+}
+function addWorkflowMessageEntries(entry, definition) {
+  if (definition.signals !== void 0 && Object.keys(definition.signals).length > 0)
+    entry.signals = buildMessageEntries(definition.type, "signal", definition.signals);
+  if (definition.updates !== void 0 && Object.keys(definition.updates).length > 0)
+    entry.updates = buildMessageEntries(definition.type, "update", definition.updates);
+  if (definition.queries !== void 0 && Object.keys(definition.queries).length > 0)
+    entry.queries = buildMessageEntries(definition.type, "query", definition.queries);
+}
+function buildMessageEntries(workflowType, messageKind, definitions) {
+  const entries = Object.create(null);
+  for (const name of Object.keys(definitions).toSorted()) {
+    const definition = definitions[name];
+    if (definition === void 0)
+      continue;
+    const entry = {}, entityName = `${workflowType}.${messageKind}.${name}`;
+    if (definition.inputSchema !== void 0)
+      entry.inputSchema = convertSchema("workflow", entityName, "inputSchema", definition.inputSchema);
+    if (definition.outputSchema !== void 0)
+      entry.outputSchema = convertSchema("workflow", entityName, "outputSchema", definition.outputSchema);
+    entries[name] = entry;
+  }
+  return entries;
+}
+export async function buildWorkflowManifestFromDefinition(definition, activityDefinitions) {
+  const entry = buildWorkflowEntry(definition), workflowScopedActivities = buildWorkflowScopedActivityContracts(activityDefinitions, definition.type), contract = toWorkflowContractDraft(definition.type, definition.version, entry, workflowScopedActivities);
+  try {
+    return await buildWorkflowRevisionManifest(contract);
+  } catch (cause) {
+    throw new RegistryManifestLimitError(definition.type, cause);
+  }
+}
+export async function buildOneWorkflowManifest(engine, definition) {
+  return buildWorkflowManifestFromDefinition(definition, engine.listWorkflowActivityDefinitions(definition.type));
+}
+export async function buildWorkflowManifestForType(engine, workflowType) {
+  const definition = engine.getWorkflowDefinition(workflowType);
+  if (definition === void 0)
+    return;
+  return buildOneWorkflowManifest(engine, definition);
+}

package/dist/core/source/errors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Rejection vocabulary and the public error thrown by dynamic workflow
+ * source validation (WFT-13/14).
+ *
+ * @module core/source/errors
+ */
+import type { WorkflowCompatibilityReason } from '../contract/compatibility.ts';
+import { WeftError } from '../weft-error.ts';
+/**
+ * One bounded, machine-readable reason a resolved workflow source was
+ * rejected — either a structural problem discovered before a manifest could
+ * even be built (`unregistered-source-kind`, `missing-export`,
+ * `ambiguous-export`, `invalid-definition`, `manifest-build-failed`), or one
+ * of {@link WorkflowCompatibilityReason}'s five reasons, reused verbatim once
+ * a manifest was built successfully and compared against the descriptor's
+ * expectations.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowSourceRejectionReason } from '@lostgradient/weft';
+ *
+ * const reasons: WorkflowSourceRejectionReason[] = ['missing-export', 'name-mismatch'];
+ * console.log(reasons.join(', '));
+ * ```
+ */
+export type WorkflowSourceRejectionReason = 'unregistered-source-kind' | 'missing-export' | 'ambiguous-export' | 'invalid-definition' | 'manifest-build-failed' | WorkflowCompatibilityReason;
+/**
+ * Thrown by `resolveWorkflowSource()` when a loaded workflow source fails
+ * validation: a structural problem (missing/ambiguous export, an
+ * export that is not a builder-produced `WorkflowDefinition`, a contract
+ * exceeding a hostile-input limit) or a `checkWorkflowCompatibility`
+ * mismatch against the descriptor's expected `name`/`revision`/
+ * `workflowVersion`/`contractHash`. Carries every applicable
+ * {@link WorkflowSourceRejectionReason}, never just the first one found.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceValidationError } from '@lostgradient/weft';
+ *
+ * declare const engine: Engine;
+ * try {
+ *   await engine.resolveWorkflowSource('checkout', 'r1');
+ * } catch (error) {
+ *   if (error instanceof WorkflowSourceValidationError) {
+ *     console.error(error.workflowName, error.revision, error.reasons);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowSourceValidationError extends WeftError<'WorkflowSourceValidationError'> {
+    readonly workflowName: string;
+    readonly revision: string;
+    readonly reasons: readonly WorkflowSourceRejectionReason[];
+    constructor(workflowName: string, revision: string, reasons: readonly WorkflowSourceRejectionReason[]);
+}

package/dist/core/source/errors.js

@@ -0,0 +1,13 @@
+import { WeftError } from "../weft-error.js";
+
+export class WorkflowSourceValidationError extends WeftError {
+  workflowName;
+  revision;
+  reasons;
+  constructor(workflowName, revision, reasons) {
+    super("WorkflowSourceValidationError", `Dynamic workflow source "${workflowName}" revision "${revision}" failed validation: ` + reasons.join(", "));
+    this.workflowName = workflowName;
+    this.revision = revision;
+    this.reasons = reasons;
+  }
+}

package/dist/core/source/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Dynamic workflow sources (WFT-13/14): a typed `workflowSource()` factory,
+ * the `WorkflowSourceDescriptor`/`WorkflowSourceHandle` types, source-kind
+ * resolution, and validation — re-exported both for the package root
+ * (`src/index.ts`) and for `core/engine/source-registration.ts` /
+ * `core/engine/source-resolution.ts`, which cannot import `internals.ts`
+ * (the only import-restricted module in this package) but need everything
+ * else here.
+ *
+ * @module core/source
+ */
+export type { WorkflowSourceDescriptor, WorkflowSourceDescriptorInput, WorkflowSourceHandle, WorkflowSourceKind, } from './types.ts';
+export { workflowSource } from './workflow-source.ts';
+export { WorkflowSourceValidationError } from './errors.ts';
+export type { WorkflowSourceRejectionReason } from './errors.ts';
+export { resolveSourceModule } from './resolvers.ts';
+export type { ResolveSourceModuleResult } from './resolvers.ts';
+export { buildExpectedManifest, validateResolvedWorkflowSource } from './validate.ts';
+export type { WorkflowSourceValidationOutcome } from './validate.ts';

package/dist/core/source/index.js

@@ -0,0 +1,4 @@
+export { workflowSource } from "./workflow-source.js";
+export { WorkflowSourceValidationError } from "./errors.js";
+export { resolveSourceModule } from "./resolvers.js";
+export { buildExpectedManifest, validateResolvedWorkflowSource } from "./validate.js";

package/dist/core/source/resolvers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The `kind -> resolver` registry for dynamic workflow sources. A resolver's
+ * only job is to turn a {@link WorkflowSourceHandle} into the raw `unknown`
+ * module value its `load()` capability produces — everything downstream
+ * (export lookup, definition validation, manifest building) lives in
+ * `validate.ts` and is identical regardless of source kind.
+ *
+ * @module core/source/resolvers
+ */
+import type { WorkflowSourceDescriptor, WorkflowSourceHandle } from './types.ts';
+/** The outcome of {@link resolveSourceModule}: either the raw loaded module value, or a short-circuit rejection reason. */
+export type ResolveSourceModuleResult = {
+    readonly ok: true;
+    readonly moduleValue: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: 'unregistered-source-kind';
+};
+/**
+ * Look up the resolver registered for `descriptor.kind` and invoke it
+ * against `handle` to produce the raw, untrusted module value. Returns
+ * `{ ok: false, reason: 'unregistered-source-kind' }` when no resolver is
+ * registered for that kind — unreachable through `workflowSource()`'s own
+ * typed surface today (`WorkflowSourceKind` is the single literal
+ * `'module'`), but a manually-constructed handle can still name an
+ * unsupported kind, so this stays a checked, structured rejection rather
+ * than an unhandled throw — the same "unreachable through the type-safe
+ * surface, exists for hostile/manually-constructed input" precedent as
+ * `manifest-version-unsupported` in `core/contract/compatibility.ts`.
+ *
+ * @example
+ * ```ts
+ * import { workflowSource } from '@lostgradient/weft';
+ *
+ * declare const loadCheckout: () => Promise<{
+ *   checkout: import('@lostgradient/weft').WorkflowDefinition<unknown, unknown, 'checkout'>;
+ * }>;
+ * const source = workflowSource(
+ *   { name: 'checkout', location: './checkout.ts', exportName: 'checkout', revision: 'r1' },
+ *   loadCheckout,
+ * );
+ * console.log(source.descriptor.kind);
+ * ```
+ */
+export declare function resolveSourceModule(descriptor: WorkflowSourceDescriptor, handle: WorkflowSourceHandle): Promise<ResolveSourceModuleResult>;

package/dist/core/source/resolvers.js

@@ -0,0 +1,9 @@
+const SOURCE_RESOLVERS = Object.freeze({
+  module: async (handle) => handle.load()
+});
+export async function resolveSourceModule(descriptor, handle) {
+  const resolver = Object.hasOwn(SOURCE_RESOLVERS, descriptor.kind) ? SOURCE_RESOLVERS[descriptor.kind] : void 0;
+  if (resolver === void 0)
+    return { ok: !1, reason: "unregistered-source-kind" };
+  return { ok: !0, moduleValue: await resolver(handle) };
+}

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

@@ -0,0 +1,211 @@
+/**
+ * Types for dynamic workflow sources (WFT-13/14): a typed, serializable
+ * {@link WorkflowSourceDescriptor} paired with a host-side loader capability
+ * that is never serialized, plus the pure type-extractor helpers
+ * {@link workflowSource} uses to preserve a literal `() => import('./x.ts')`
+ * import's exact `TInput`/`TOutput`/`TServices` inference through to the
+ * returned {@link WorkflowSourceHandle}.
+ *
+ * @module core/source/types
+ */
+import type { WorkflowDefinition } from '../types.ts';
+/**
+ * The kind of location a {@link WorkflowSourceDescriptor} names. `'module'`
+ * is the only kind today — a literal ES module import resolved by a host
+ * loader. The union is a single literal rather than `string` so a future
+ * source kind (a bundle registry entry, a remote fetch) can be added without
+ * a breaking change to this type.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowSourceKind } from '@lostgradient/weft';
+ *
+ * const kind: WorkflowSourceKind = 'module';
+ * console.log(kind);
+ * ```
+ */
+export type WorkflowSourceKind = 'module';
+/**
+ * Plain, serializable metadata identifying one dynamic workflow source:
+ * where a workflow's code lives (`location`), which named export holds the
+ * workflow definition (`exportName`), and the exact revision the caller
+ * expects (`revision`), plus optional pinned `workflowVersion`/`contractHash`
+ * expectations. Deliberately carries no function reference — the loader
+ * capability that actually resolves `location` into a module value is a
+ * separate, never-serialized field on {@link WorkflowSourceHandle}. A
+ * descriptor is safe to log, persist, or send over the wire; nothing here
+ * can execute code.
+ *
+ * `TName` is a phantom convenience for callers that want to brand a
+ * descriptor with a specific workflow name at the type level (for example
+ * a lookup table keyed by name); {@link WorkflowSourceHandle} itself always
+ * carries the unparameterized (`TName = string`) shape, since the
+ * descriptor's `name` field holds whatever string the caller supplied and
+ * is only checked against the loaded module's actual name at resolve time
+ * — see `resolveWorkflowSource`'s `name-mismatch` rejection reason.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowSourceDescriptor } from '@lostgradient/weft';
+ *
+ * const descriptor: WorkflowSourceDescriptor = {
+ *   kind: 'module',
+ *   name: 'checkout',
+ *   location: './workflows/checkout.ts',
+ *   exportName: 'checkout',
+ *   revision: 'checkout-2026.09.01',
+ * };
+ * console.log(descriptor.kind);
+ * ```
+ */
+export interface WorkflowSourceDescriptor<TName extends string = string> {
+    /** Which resolver (`core/source/resolvers.ts`) loads this source. */
+    readonly kind: WorkflowSourceKind;
+    /** The workflow name this source is expected to resolve to. */
+    readonly name: TName;
+    /**
+     * Host-meaningful location string (a module specifier for `kind: 'module'`).
+     * Carried verbatim — never parsed, concatenated, or used to construct an
+     * import specifier by this package; the loader capability alone is
+     * responsible for turning `location` into a loaded module.
+     */
+    readonly location: string;
+    /** The named export within the loaded module that holds the workflow definition. */
+    readonly exportName: string;
+    /** The caller's expected content-derived revision; compared against the revision actually derived from the loaded contract. */
+    readonly revision: string;
+    /** Optional pinned workflow version; compared for exact string equality via `checkWorkflowCompatibility` (`checkVersionCompatibility()`'s entire contract is `storedVersion === registeredVersion` — there is no semver-range matching) when set. */
+    readonly workflowVersion?: string;
+    /** Optional pinned contract hash; compared for exact equality when set. */
+    readonly contractHash?: string;
+}
+/**
+ * The loose input shape {@link workflowSource} accepts before `kind`
+ * defaults to `'module'` — every {@link WorkflowSourceDescriptor} field
+ * except `kind`, which callers may omit for the only kind that exists today.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowSourceDescriptorInput } from '@lostgradient/weft';
+ *
+ * const input: WorkflowSourceDescriptorInput<'checkout'> = {
+ *   name: 'checkout',
+ *   location: './workflows/checkout.ts',
+ *   exportName: 'checkout',
+ *   revision: 'checkout-2026.09.01',
+ * };
+ * console.log(input.exportName);
+ * ```
+ */
+export type WorkflowSourceDescriptorInput<TExportName extends string> = {
+    readonly kind?: WorkflowSourceKind;
+    readonly name: string;
+    readonly location: string;
+    readonly exportName: TExportName;
+    readonly revision: string;
+    readonly workflowVersion?: string;
+    readonly contractHash?: string;
+};
+/**
+ * A typed handle pairing a serializable {@link WorkflowSourceDescriptor}
+ * with the host-side loader capability that resolves it — the value
+ * `workflowSource()` returns. `load` is a plain `() => Promise<unknown>`
+ * at the type level; when built from a literal `() => import('./x.ts')`
+ * import, `TInput`/`TOutput`/`TName`/`TServices` are inferred from the
+ * named export the descriptor points at, so `engine.registerSource(handle)`
+ * and a later `resolveWorkflowSource` can carry that inference through
+ * without a cast. `TInput`/`TOutput`/`TName`/`TServices` are phantom —
+ * carried only as optional, never-populated marker fields — mirroring
+ * `BuiltWorkflowDefinition`'s own phantom-marker convention
+ * (`core/types/workflow-builder.ts`).
+ *
+ * @example
+ * ```ts
+ * import { workflowSource } from '@lostgradient/weft';
+ * import type { WorkflowSourceHandle } from '@lostgradient/weft';
+ *
+ * declare const loadCheckout: () => Promise<{
+ *   checkout: import('@lostgradient/weft').WorkflowDefinition<{ orderId: string }, { shipped: boolean }, 'checkout'>;
+ * }>;
+ * const source: WorkflowSourceHandle = workflowSource(
+ *   { name: 'checkout', location: './workflows/checkout.ts', exportName: 'checkout', revision: 'r1' },
+ *   loadCheckout,
+ * );
+ * console.log(source.descriptor.name);
+ * ```
+ */
+export interface WorkflowSourceHandle<TInput = unknown, TOutput = unknown, TName extends string = string, TServices = unknown> {
+    /** Plain, serializable source metadata. Never carries a function reference. */
+    readonly descriptor: WorkflowSourceDescriptor;
+    /**
+     * Host-side loader capability. Never serialized; concurrent
+     * `resolveWorkflowSource()` calls for the same `(name, revision)` share
+     * exactly one in-flight invocation (single-flight), so it is invoked at
+     * most once per key PER ATTEMPT. It is not limited to one invocation for
+     * the key's entire lifetime: `getOrCreateSharedSourceLoad()` removes the
+     * shared promise once it settles, so if that attempt's load, validation,
+     * or catalog install fails, a later `resolveWorkflowSource()` call for the
+     * same `(name, revision)` starts a fresh attempt and invokes the loader
+     * again. A successful attempt is cached — see `resolveWorkflowSource`.
+     */
+    readonly load: () => Promise<unknown>;
+    /** Phantom marker for the resolved workflow's input type. Not present at runtime. */
+    readonly _input?: TInput;
+    /** Phantom marker for the resolved workflow's output type. Not present at runtime. */
+    readonly _output?: TOutput;
+    /** Phantom marker for the resolved workflow's literal name type. Not present at runtime. */
+    readonly _name?: TName;
+    /** Phantom marker for the resolved workflow's per-run services type. Not present at runtime. */
+    readonly _services?: TServices;
+}
+/**
+ * `true` when `T` is exactly `any` — used to reject a `workflowSource()`
+ * call whose loader's module type could not be inferred (a dynamic
+ * `import(pathVariable)`, which TypeScript types as `Promise<any>`).
+ * Distinguishing `any` from a genuine `Record<string, unknown>` requires
+ * this "does `T` accept both `0` and `1`" trick rather than `T extends
+ * Record<string, unknown>` — `any` would trivially satisfy that constraint
+ * too, silently defeating the whole point of requiring a literal import.
+ *
+ * @example
+ * ```ts
+ * import type { IsAny } from './types.ts';
+ *
+ * type CheckConcrete = IsAny<{ a: 1 }>;
+ * const concrete: CheckConcrete = false;
+ * console.log(concrete);
+ * ```
+ */
+export type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * Resolve the exact export type at `TExportName` on `TModule`, narrowed to
+ * `WorkflowDefinition` — or `never` when that export is not one. Feeding
+ * `never` into {@link InputOf} / {@link OutputOf} / {@link NameOf} /
+ * {@link ServicesOf} collapses each to `never` too (conditional types
+ * distribute over `never`, TypeScript's "empty union" case), which is how a
+ * `workflowSource()` call pointed at a non-workflow export compiles at the
+ * call site but produces a handle whose type parameters are unusable —
+ * misuse fails at first *use* of the handle rather than at the
+ * `workflowSource()` call itself. See `workflow-source.test-d.ts` for the
+ * regression pin.
+ *
+ * @example
+ * ```ts
+ * import type { ModuleWorkflowDefinition } from './types.ts';
+ * import type { WorkflowDefinition } from '@lostgradient/weft';
+ *
+ * type Module = { checkout: WorkflowDefinition<{ orderId: string }, { shipped: boolean }, 'checkout'> };
+ * type Resolved = ModuleWorkflowDefinition<Module, 'checkout'>;
+ * declare const resolved: Resolved;
+ * console.log(resolved.name);
+ * ```
+ */
+export type ModuleWorkflowDefinition<TModule extends Record<string, unknown>, TExportName extends keyof TModule & string> = TModule[TExportName] extends WorkflowDefinition<infer _TInput, infer _TOutput, infer _TName, infer _TServices> ? TModule[TExportName] : never;
+/** Extract `TInput` from a `WorkflowDefinition`-shaped type, or `never`. */
+export type InputOf<T> = T extends WorkflowDefinition<infer TInput, infer _TOutput, infer _TName, infer _TServices> ? TInput : never;
+/** Extract `TOutput` from a `WorkflowDefinition`-shaped type, or `never`. */
+export type OutputOf<T> = T extends WorkflowDefinition<infer _TInput, infer TOutput, infer _TName, infer _TServices> ? TOutput : never;
+/** Extract the literal `TName` from a `WorkflowDefinition`-shaped type, or `never`. */
+export type NameOf<T> = T extends WorkflowDefinition<infer _TInput, infer _TOutput, infer TName, infer _TServices> ? TName : never;
+/** Extract `TServices` from a `WorkflowDefinition`-shaped type, or `never`. */
+export type ServicesOf<T> = T extends WorkflowDefinition<infer _TInput, infer _TOutput, infer _TName, infer TServices> ? TServices : never;